From b06d78bccaca27f46113af787745f6c1c8011101 Mon Sep 17 00:00:00 2001 From: "well-architected-sync-bot[bot]" <235114805+well-architected-sync-bot[bot]@users.noreply.github.com> Date: Wed, 26 Aug 2026 10:28:19 +0000 Subject: [PATCH] Sync from github/github-well-architected-internal (main) Source Repository: github/github-well-architected-internal Source Branch: main Source SHA: 7af03199111cbe68d0f1ea667b2acff1b0470d2e --- .../library/application-security/checklist.md | 2 +- .../application-security/quick-links.md | 26 ++--- .../recommendations/actions-security.md | 45 +++++---- .../recommendations/enforce-ghas-at-scale.md | 34 +++---- .../managing-dependency-threats.md | 28 +++--- .../recommendations/prioritizing-alerts.md | 12 +-- .../securing-developer-workspace.md | 42 ++++---- content/library/architecture/quick-links.md | 42 ++++---- .../deploying-actions-runner-controller.md | 16 +-- ...anding-enterprise-custom-agents-context.md | 12 +-- .../hosted-runner-private-networking.md | 28 +++--- .../large-git-repositories.md | 10 +- .../when-to-use-git-lfs.md | 4 +- content/library/collaboration/quick-links.md | 5 +- .../applying-devops-methodology.md | 4 +- .../scaling-actions-reusability.md | 13 ++- content/library/governance/quick-links.md | 14 +-- .../agentic-engineering-system-on-github.md | 12 +-- .../agentic-governance-taxonomy.md | 10 +- .../agentic-shared-knowledge.md | 10 +- .../governance-administration-essentials.md | 66 ++++++------- .../governance-policies-best-practices.md | 4 +- .../governing-agentic-workflows.md | 2 +- .../recommendations/governing-agents.md | 98 +++++++++---------- .../recommendations/managing-ai-credits.md | 6 +- .../rulesets-best-practices.md | 4 +- content/library/overview/overview.md | 4 +- .../library/productivity/design-principles.md | 2 +- content/library/productivity/quick-links.md | 16 +-- .../adopting-copilot-at-scale.md | 18 ++-- .../engineering-system-metrics.md | 2 +- .../scenarios/measuring-genai-impact.md | 6 +- .../02-source-environment-assessment.md | 22 ++--- .../03-target-environment.md | 28 +++--- .../04-migration-testing.md | 10 +- .../05-repository-migration.md | 17 ++-- .../06-post-migration.md | 8 +- .../azure-devops-migration-guide/overview.md | 10 +- .../migrations/repository-checklist.md | 22 ++--- .../scenarios/nist-ssdf-implementation.md | 24 ++--- 40 files changed, 365 insertions(+), 373 deletions(-) diff --git a/content/library/application-security/checklist.md b/content/library/application-security/checklist.md index 974035d..defd820 100644 --- a/content/library/application-security/checklist.md +++ b/content/library/application-security/checklist.md @@ -183,7 +183,7 @@ This assessment checklist focuses on evaluating and enhancing the **Application - **Repository Structure:** - Assess the organization and structure of repositories for clarity and scalability. - Determine whether repositories follow a naming convention, and ensure all repositories have a description. - - Check for the use of [custom properties](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) to dynamically manage and enforce. + - Check for the use of [custom properties](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) to organize repositories and target them with rulesets. - Verify that repositories are appropriately segmented as to avoid monolithic structures unnecessarily, or determine the necessity of such an architecture. - Check for the use of branch protection rules to maintain code quality. diff --git a/content/library/application-security/quick-links.md b/content/library/application-security/quick-links.md index 9e1d918..c3fe862 100644 --- a/content/library/application-security/quick-links.md +++ b/content/library/application-security/quick-links.md @@ -11,28 +11,28 @@ A curated list of resources and tools to enhance security across the **Applicati ## Security -- [GitHub Advanced Security](https://docs.github.com/en/github/getting-started-with-github/about-github-advanced-security) -- [Securing your organization](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization) -- [Fixing security alerts at scale](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale) -- [Microsoft Azure Security Center](https://learn.microsoft.com/en-us/azure/security-center/security-center-introduction) +- [About GitHub Advanced Security](https://docs.github.com/get-started/learning-about-github/about-github-advanced-security) +- [Configuring security features in your organization](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/secure-at-scale/configure-organization-security) +- [Running a security campaign to fix alerts at scale](https://docs.github.com/enterprise-cloud@latest/code-security/tutorials/secure-your-organization/best-practice-fix-alerts-at-scale) +- [What is Microsoft Defender for Cloud?](https://learn.microsoft.com/en-us/azure/defender-for-cloud/defender-for-cloud-introduction) ## Compliance -- [Accessing compliance reports for your enterprise](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/accessing-compliance-reports-for-your-enterprise) -- [Microsoft Compliance Offerings](https://learn.microsoft.com/en-us/compliance/regulatory/offering-home) -- [GitHub Subprocessors](https://docs.github.com/en/site-policy/privacy-policies/github-subprocessors) +- [Accessing compliance reports for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/overview/accessing-compliance-reports-for-your-enterprise) +- [Microsoft compliance offerings](https://learn.microsoft.com/en-us/compliance/regulatory/offering-home) +- [GitHub Subprocessors](https://docs.github.com/site-policy/privacy-policies/github-subprocessors) ## Proactivity -- [Keeping your dependencies updated automatically with Dependabot version updates](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-version-updates) -- [Configuring Dependabot security updates](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates) -- [Configuring Dependency Review to catch vulnerable dependencies in your pull requests](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review) -- [Configuring Push Protection to block commits with hard coded secrets](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/push-protection-for-repositories-and-organizations) +- [Dependabot version updates](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-version-updates) +- [Configuring Dependabot security updates](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configure-security-updates) +- [Dependency review](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependency-review) +- [Push protection](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/secret-security/push-protection) - [Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns) ## Awareness - [GitHub Security Alerts](https://github.blog/news-insights/product-news/introducing-security-alerts-on-github/) -- [Working with security advisories](https://docs.github.com/en/enterprise-cloud@latest/code-security/security-advisories) +- [How-tos for fixing vulnerabilities](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities) - [Azure Security Blog](https://azure.microsoft.com/en-us/blog/category/security/) -- [Microsoft Learn: Security, Compliance, and Identity Fundamentals](https://learn.microsoft.com/en-us/credentials/certifications/security-compliance-and-identity-fundamentals/?practice-assessment-type=certification) +- [Microsoft Certified: Security, Compliance, and Identity Fundamentals](https://learn.microsoft.com/en-us/credentials/certifications/security-compliance-and-identity-fundamentals/?practice-assessment-type=certification) diff --git a/content/library/application-security/recommendations/actions-security.md b/content/library/application-security/recommendations/actions-security.md index 394c712..0908527 100644 --- a/content/library/application-security/recommendations/actions-security.md +++ b/content/library/application-security/recommendations/actions-security.md @@ -87,51 +87,51 @@ To secure GitHub Actions workflows, consider the following strategies: 6. **Avoid actions with mutable dependencies**: Do not use actions that include mutable dependencies (e.g. `latest`) or pull in external binaries without verification, as they introduce supply chain risks. 7. **Avoid workflow injection**: Sanitize user input and avoid using expression values in sensitive contexts (such as `run` steps) to prevent injection attacks. 8. **Avoid `pull_request_target`**: This event runs workflows in the base repository context with elevated permissions. This can enable malicious execution using pull requests from forks. -9. **Secure `workflow_run` workflows**: Treat all artifacts, code, and data from triggering workflows as untrusted. Use [branch filters](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#limiting-your-workflow-to-run-based-on-branches) and validate all inputs. +9. **Secure `workflow_run` workflows**: Treat all artifacts, code, and data from triggering workflows as untrusted. Use [branch filters](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows#limiting-your-workflow-to-run-based-on-branches) and validate all inputs. 10. **Use `head.sha` instead of `head.ref`**: Where possible, reference by commit SHA instead of a user-provided branch name or tag (ref), especially in sensitive contexts (such as `run` steps). If require, use environment variable to store `head.ref` and reference it to prevent injection attack. 11. **Use caution with public repositories**: Anyone can suggest changes to public repositories. Review workflow triggers, and never use self-hosted runners with public repositories. -12. **Restrict allowed actions**: Use the [*Allow enterprise, and select non-enterprise, actions and reusable workflows*](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#controlling-access-to-public-actions-and-reusable-workflows) setting to control which actions can run. +12. **Restrict allowed actions**: Use the [*Allow enterprise, and select non-enterprise, actions and reusable workflows*](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#controlling-access-to-public-actions-and-reusable-workflows) setting to control which actions can run. ## Assumptions and preconditions -This article assumes readers are familiar with [GitHub Actions](https://docs.github.com/en/enterprise-cloud@latest/actions/about-github-actions/understanding-github-actions) and have experience creating and managing workflows. It also assumes a basic understanding of security best practices and concepts such as authentication, authorization, and OIDC. +This article assumes readers are familiar with [GitHub Actions](https://docs.github.com/enterprise-cloud@latest/actions/get-started/understand-github-actions) and have experience creating and managing workflows. It also assumes a basic understanding of security best practices and concepts such as authentication, authorization, and OIDC. ## Recommended implementation ### Use OpenID Connect (OIDC) for authentication -CI/CD platforms like GitHub Actions often require access to sensitive resources such as source code repositories, build artifacts, and deployment environments. To ensure that only authorized users and services can access these resources, [use OpenID Connect (OIDC) for authentication](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect). +CI/CD platforms like GitHub Actions often require access to sensitive resources such as source code repositories, build artifacts, and deployment environments. To ensure that only authorized users and services can access these resources, [use OpenID Connect (OIDC) for authentication](https://docs.github.com/actions/concepts/security/openid-connect). OIDC eliminates the need for long-lived credentials in Actions secrets, reducing the risk of secret exfiltration. By establishing trust between GitHub Actions and a service that supports OIDC, attributes like organization, repository, workflow, or user can be used as conditions to approve or deny access. #### Configuring trust relationships with specific claims -When [configuring OIDC trust relationships with cloud providers](https://docs.github.com/en/actions/reference/security/oidc#oidc-claims-used-to-define-trust-conditions-on-cloud-roles) or compliant services, specify granular claims to restrict access to trusted conditions. For example: +When [configuring OIDC trust relationships with cloud providers](https://docs.github.com/actions/reference/security/oidc#oidc-claims-used-to-define-trust-conditions-on-cloud-roles) or compliant services, specify granular claims to restrict access to trusted conditions. For example: - **`sub` claim**: The primary OIDC subject identifier, uniquely representing the repository that requested the token. Use this claim to restrict access to specific repositories and environments. Prefer an exact match on a complete claim instead of wildcard matches. - **`job_workflow_ref` claim**: Specifies the exact workflow file path and commit SHA. Note that only a limited number of cloud providers support this custom claim (e.g. [Azure](https://learn.microsoft.com/en-us/entra/workload-id/workload-identities-flexible-federated-identity-credentials?tabs=github)). -Define the most granular trust conditions wherever possible to prevent unauthorized access, even from legitimate repositories. [Customize the `sub` claim](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc#customizing-the-token-claims) when the cloud provider's OIDC implementation does not support matching **custom claims** or you need immutable identifiers in the `sub`. +Define the most granular trust conditions wherever possible to prevent unauthorized access, even from legitimate repositories. [Customize the `sub` claim](https://docs.github.com/enterprise-cloud@latest/actions/reference/security/oidc#customizing-the-token-claims) when the cloud provider's OIDC implementation does not support matching **custom claims** or you need immutable identifiers in the `sub`. - Prefer **immutable identifiers** (e.g., `repository_owner_id:12345:repository_id:67890`) over mutable ones (e.g., `repo:github/some-repo`). #### Scaling with reusable workflows -OIDC can also [secure reusable workflows](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows) across multiple organizations and repositories. Use `job_workflow_ref` to ensure only approved workflows access sensitive resources. +OIDC can also [secure reusable workflows](https://docs.github.com/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows) across multiple organizations and repositories. Use `job_workflow_ref` to ensure only approved workflows access sensitive resources. ### Configure repository rules Repository rulesets provide a strong defensive layer that complements workflow-level security measures. Consider these rules: -- [Require pull requests before merging](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging): Enforce human review to detect malicious changes. For example, require human review and at least two reviewers to merge to the default branch. -- [Require status checks to pass before merging](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-status-checks-to-pass-before-merging): Ensure automated validation checks pass before merging. -- [Require code scanning results](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-code-scanning-results): Identify security vulnerabilities before merge. -- [Require signed commits](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits): Ensure all commits are signed to prove who authored them and that they haven't been modified. +- [Require pull requests before merging](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging): Enforce human review to detect malicious changes. For example, require human review and at least two reviewers to merge to the default branch. +- [Require status checks to pass before merging](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-status-checks-to-pass-before-merging): Ensure automated validation checks pass before merging. +- [Require code scanning results](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-code-scanning-results): Identify security vulnerabilities before merge. +- [Require signed commits](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits): Ensure all commits are signed to prove who authored them and that they haven't been modified. - Restrict bypass permissions: Limit bypass capabilities to emergencies and monitor via audit logs. ### Implement least privilege for workflow permissions -GitHub Actions workflows include a pre-defined `GITHUB_TOKEN` variable that grants [default permissions](https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) to jobs in the workflow. These default permissions can be configured as either **permissive** or **restricted** at the [organization level](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization) or at the [repository level](https://docs.github.com/en/enterprise-cloud@latest/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). +GitHub Actions workflows include a pre-defined `GITHUB_TOKEN` variable that grants [default permissions](https://docs.github.com/enterprise-cloud@latest/actions/tutorials/authenticate-with-github_token) to jobs in the workflow. These default permissions can be configured as either **permissive** or **restricted** at the [organization level](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization) or at the [repository level](https://docs.github.com/enterprise-cloud@latest/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). Set the organization-level or repository-level default to **restricted** (read-only). Then, define permissions explicitly at the job level using the `jobs..permissions` section. Avoid setting workflow-level permissions globally (at the top of the workflow file) as this grants the same permissions to all jobs. This approach: @@ -165,14 +165,14 @@ jobs: ### Use Dependabot to protect the supply chain -[Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/dependabot-quickstart-guide) is a GitHub feature that automatically identifies outdated or vulnerable dependencies across repositories and creates pull requests to update them. By enabling Dependabot, teams can ensure that: +[Dependabot](https://docs.github.com/enterprise-cloud@latest/code-security/tutorials/secure-your-dependencies/dependabot-quickstart) is a GitHub feature that automatically identifies outdated or vulnerable dependencies across repositories and creates pull requests to update them. By enabling Dependabot, teams can ensure that: - Actions used in workflows are up to date - Container images, packages, and other dependencies in the repository are secure - The supply chain is monitored for vulnerabilities {{< callout type="warning" >}} -Dependabot will only create Dependabot alerts for vulnerable GitHub Actions that use semantic versioning. Actions pinned to SHAs will only receive version updates, not security alerts. For more information, see [About Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). +Dependabot will only create Dependabot alerts for vulnerable GitHub Actions that use semantic versioning. Actions pinned to SHAs will only receive version updates, not security alerts. For more information, see [Dependabot alerts](https://docs.github.com/code-security/concepts/supply-chain-security/dependabot-alerts). {{< /callout >}} ### Pin versions of actions @@ -201,7 +201,7 @@ To avoid using actions with mutable dependencies, review actions source code and Avoid inserting untrusted input into any executable context such as `run:` blocks using expressions. Values like issue titles, PR bodies, and branch names can be manipulated by attackers to inject malicious commands. Use environment variables to safely incorporate user input. -For more details on the risk of workflow script injections and mitigation strategies, refer to [GitHub Docs](https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections). +For more details on the risk of workflow script injections and mitigation strategies, refer to [Secure use reference](https://docs.github.com/enterprise-cloud@latest/actions/reference/security/secure-use). ### Avoid `pull_request_target` @@ -244,7 +244,7 @@ Avoid use self-hosted runners with public repositories. When a public repository - Poisoning caches that could affect other repositories or workflows {{< /callout >}} -If allowing pull requests from forks, consider enabling "[require approval for all outside collaborators](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories)" to require approval before workflows run on fork PRs. +If allowing pull requests from forks, consider enabling "[require approval for all outside collaborators](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories)" to require approval before workflows run on fork PRs. Even ephemeral self-hosted runners carry risks in public repository contexts, as attackers can exploit the window between job start and completion, or leverage shared resources like caches. @@ -254,7 +254,7 @@ GitHub-hosted runners are network isolated by default. They can make outbound ca ### Restrict allowed actions -The [allowed actions and reusable workflows setting](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#allowing-select-actions-and-reusable-workflows-to-run) controls which actions can run (or not run) in your organization or enterprise. This provides centralized governance and makes it easy to respond to compromised actions without searching across repositories. +The [allowed actions and reusable workflows setting](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#allowing-select-actions-and-reusable-workflows-to-run) controls which actions can run (or not run) in your organization or enterprise. This provides centralized governance and makes it easy to respond to compromised actions without searching across repositories. Consider defining the list of allowed actions using policy as code (e.g., via Terraform or the REST API) to establish a request/approval process, track changes for audit purposes, and improve visibility into which actions are allowed. @@ -262,7 +262,7 @@ Consider defining the list of allowed actions using policy as code (e.g., via Te ### Pinning actions based on a version tag -Although pinning to a commit hash is the most secure option, specifying a tag is more convenient and widely used. If specifying a tag, ensure the action's creators are trusted. The ["Verified creator"](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace#about-badges-in-github-marketplace) badge on GitHub Marketplace is a useful signal, but it is not a guarantee of security. +Although pinning to a commit hash is the most secure option, specifying a tag is more convenient and widely used. If specifying a tag, ensure the action's creators are trusted. The ["Verified creator"](https://docs.github.com/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace#about-badges-in-github-marketplace) badge on GitHub Marketplace is a useful signal, but it is not a guarantee of security. For the most secure footprint, trust no one, review the code, and always use commit SHAs. @@ -280,11 +280,10 @@ For the most secure footprint, trust no one, review the code, and always use com Specific helpful articles: -- [Security Hardening for GitHub Actions](https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) -- [Self-hosted runner security](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) -- [Events that trigger workflows](https://docs.github.com/en/enterprise-cloud@latest/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows) -- [OIDC token claims](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc#oidc-token-claims) -- [Secure use reference](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/secure-use) +- [Self-hosted runners reference](https://docs.github.com/actions/reference/runners/self-hosted-runners) +- [Events that trigger workflows](https://docs.github.com/enterprise-cloud@latest/actions/reference/workflows-and-actions/events-that-trigger-workflows) +- [OIDC token claims](https://docs.github.com/enterprise-cloud@latest/actions/reference/security/oidc#oidc-token-claims) +- [Secure use reference](https://docs.github.com/enterprise-cloud@latest/actions/reference/security/secure-use) ### External Resources diff --git a/content/library/application-security/recommendations/enforce-ghas-at-scale.md b/content/library/application-security/recommendations/enforce-ghas-at-scale.md index 7b8f736..c673441 100644 --- a/content/library/application-security/recommendations/enforce-ghas-at-scale.md +++ b/content/library/application-security/recommendations/enforce-ghas-at-scale.md @@ -104,13 +104,13 @@ These recommendations assume that you have the following: A consistent branching strategy across repositories will make it easier to enforce GHAS at scale. This is because enforcement can be implemented as a requirement before code is merged into a target branch. -One popular branching strategy is [GitHub Flow](https://docs.github.com/en/enterprise-cloud@latest/get-started/using-github/github-flow), where the `main` branch is the default branch for all repositories and represents deployable, production code. Developers create feature branches off of `main` to work on new features or bug fixes. When a feature is ready for review, a Pull Request is created to merge the feature branch back into `main`. +One popular branching strategy is [GitHub Flow](https://docs.github.com/enterprise-cloud@latest/get-started/using-github/github-flow), where the `main` branch is the default branch for all repositories and represents deployable, production code. Developers create feature branches off of `main` to work on new features or bug fixes. When a feature is ready for review, a Pull Request is created to merge the feature branch back into `main`. Another common branching strategy is [Git Flow](https://git-scm.com/about/branching-and-merging), which uses `main` as the production branch and `develop` as the integration branch. Feature branches are created off of `develop` and merged back into `develop` via Pull Requests. When `develop` is ready for a release, it is merged into `main`. ### Manage repositories with custom properties -Repository [custom properties](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) can be used to store metadata about a repository, such as its business criticality, or its security and compliance requirements. This metadata can be set via API, and can be used to dynamically manage and govern repositories at scale through built-in integrations with other native GitHub features such as Security Configurations and Repository Rulesets. +Repository [custom properties](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) can be used to store metadata about a repository, such as its business criticality, or its security and compliance requirements. This metadata can be set via API, and can be used to dynamically manage and govern repositories at scale through built-in integrations with other native GitHub features such as Security Configurations and Repository Rulesets. {{< callout type="info" >}} Repository custom properties are available in GitHub Enterprise Cloud and GitHub Enterprise Server 3.13 and later. @@ -118,7 +118,7 @@ Repository custom properties are available in GitHub Enterprise Cloud and GitHub ### Use Security Configurations where possible -[Security Configurations](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories) are collections of enablement settings for GitHub's application security features that you can apply to any repository within your Organization. You can create a Security Configuration that includes the GHAS scanning features you want to enforce, and apply it to all repositories based on custom property values. +[Security Configurations](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/security-at-scale/organization-security) are collections of enablement settings for GitHub's application security features that you can apply to any repository within your Organization. You can create a Security Configuration that includes the GHAS scanning features you want to enforce, and apply it to all repositories based on custom property values. {{< callout type="info" >}} Security Configurations are available in GitHub Enterprise Cloud and GitHub Enterprise Server 3.15 and later. @@ -128,7 +128,7 @@ Security Configurations are available in GitHub Enterprise Cloud and GitHub Ente Depending on your requirements, you may want to enforce GHAS at scale based on a set of conditions that are not covered by Security Configurations. -[Repository Rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) allow you to restrict merges to target branches, for target repositories, until a defined set of conditions are met. You can create Rulesets that require custom workflows to pass before code can be merged, and apply them to repositories based on naming convention or custom property values. +[Repository Rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) allow you to restrict merges to target branches, for target repositories, until a defined set of conditions are met. You can create Rulesets that require custom workflows to pass before code can be merged, and apply them to repositories based on naming convention or custom property values. {{< callout type="info" >}} Repository Rulesets are available in GitHub Enterprise Cloud and GitHub Enterprise Server 3.11 and later. @@ -142,15 +142,15 @@ Enforcing _secret scanning_ as part of a Security Configuration will raise alert Enforcing _push protection_ as part of a Security Configuration will stop new secrets from being pushed to repositories. -By default, anyone with `Write` access to a repository has the ability to bypass push protection. This ability can be restricted by [enabling delegated bypass for push protection](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/push-protection-for-repositories-and-organizations#enabling-delegated-bypass-for-push-protection). +By default, anyone with `Write` access to a repository has the ability to bypass push protection. This ability can be restricted by [enabling delegated bypass for push protection](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/secure-your-secrets/manage-bypass-requests/enable-delegated-bypass). -Users with `Write` access to a repository can add a `secret_scanning.yml` file to the `.github` directory of a repository to exclude certain files or filepaths from secret scanning. To prevent this file from being created across an Organization, configure a [push ruleset](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#creating-a-push-ruleset) that restricts pushes to the path `.github/secret_scanning.yml` across all repositories. +Users with `Write` access to a repository can add a `secret_scanning.yml` file to the `.github` directory of a repository to exclude certain files or filepaths from secret scanning. To prevent this file from being created across an Organization, configure a [push ruleset](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#creating-a-push-ruleset) that restricts pushes to the path `.github/secret_scanning.yml` across all repositories. ### Enforcing Dependency Scanning -Scanning existing dependencies in a repository can be enforced by enabling [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/dependabot-quickstart-guide) within a Security Configuration. Dependabot will raise alerts when a vulnerable dependency is detected in a repository, and [Security Updates](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) will automatically create a Pull Request to update the vulnerable dependency to a non-vulnerable version. +Scanning existing dependencies in a repository can be enforced by enabling [Dependabot](https://docs.github.com/enterprise-cloud@latest/code-security/tutorials/secure-your-dependencies/dependabot-quickstart) within a Security Configuration. Dependabot will raise alerts when a vulnerable dependency is detected in a repository, and [Security Updates](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-security-updates) will automatically create a Pull Request to update the vulnerable dependency to a non-vulnerable version. -To prevent new vulnerable dependencies from being added to target repositories, you can define a centralized [reusable workflow](https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/reusing-workflows) that makes use of [Dependency Review](https://docs.github.com/en/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review), a GitHub Action that evaluates changes to dependency manifest files, and include that workflow as a [required workflow](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging) within a Repository Ruleset. +To prevent new vulnerable dependencies from being added to target repositories, you can define a centralized [reusable workflow](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/reuse-automations/reuse-workflows) that makes use of [Dependency Review](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependency-review), a GitHub Action that evaluates changes to dependency manifest files, and include that workflow as a [required workflow](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging) within a Repository Ruleset. Dependency Review can be configured to fail a status check on the Pull Request, thus blocking Pull Request merges if a commit either introduces a net new vulnerability that surpasses a specific severity, or if the commit introduces a dependency with a specific software license. @@ -160,7 +160,7 @@ To configure and enforce a centralized Dependency Review workflow: {{< callout type="info" >}} If you opt for a `private` repository, only other `private` repositories will be able to use the workflow. {{< /callout >}} -2. Update the repository's settings to [make the workflow accessible by other repositories](https://docs.github.com/en/enterprise-cloud@latest/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). +2. Update the repository's settings to [make the workflow accessible by other repositories](https://docs.github.com/enterprise-cloud@latest/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). 3. Under the `.github/workflows` directory of the repository, create a new workflow file that uses the [actions/dependency-review](https://github.com/actions/dependency-review-action) Action, similar to the example below: ```yaml @@ -191,13 +191,13 @@ jobs: ``` 4. Set the configuration parameters for Dependency Review (under the `with:` key) to meet your Organization's requirements. For a full list of configuration options, see the [Dependency Review Action documentation](https://github.com/actions/dependency-review-action#configuration-options). -5. Ensure that your Repository Ruleset is configured to [require your newly defined workflow to pass before merging](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging). +5. Ensure that your Repository Ruleset is configured to [require your newly defined workflow to pass before merging](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging). ### Enforcing Code Scanning When enforcing code scanning, there are two popular options: -1. **Security Configurations** - Security Configurations provide an easy way to enforce [Code Scanning Default Setup](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning), which leverages [CodeQL](https://codeql.github.com/). +1. **Security Configurations** - Security Configurations provide an easy way to enforce [Code Scanning Default Setup](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configure-code-scanning), which leverages [CodeQL](https://codeql.github.com/). 2. **Required workflows with Repository Rulesets** - With Repository Rulesets, you can create centralized GitHub Actions workflows that must run and pass before code can be merged into a target branch. With either option, it's important to consider the programming languages used in the repositories that you're targeting. Compiled languages (like C/C++, C#, Java, and Go) are more likely to run into code scanning errors if the scan is run without following the application's proper build steps. Interpreted languages (like Python, Ruby, and JavaScript/TypeScript) are much less likely to run into these issues. @@ -206,7 +206,7 @@ You can use utilities like [this GitHub CLI extension](https://github.com/CallMe ### Access permissions -When enforcing GHAS at scale, it is important to ensure that the right people have the right level of access to security alerts. This may entail creating custom roles with specific permissions to alerts, or using the [default repository roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in GitHub. +When enforcing GHAS at scale, it is important to ensure that the right people have the right level of access to security alerts. This may entail creating custom roles with specific permissions to alerts, or using the [default repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in GitHub. The following table illustrates access permissions to alerts for the five default repository roles in GitHub: @@ -220,19 +220,19 @@ The following table illustrates access permissions to alerts for the five defaul _\*By default, the commit author for a secret scanning alert has write access to the alert._ -Separate from the default repository roles, there is a pre-defined Organization role, [Security manager](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization), which is a great option for personas who need `Read` access to all repositories in the Organization, and `Write` access to all security alerts in the Organization. +Separate from the default repository roles, there is a pre-defined Organization role, [Security manager](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization), which is a great option for personas who need `Read` access to all repositories in the Organization, and `Write` access to all security alerts in the Organization. -[Custom roles](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization) can be created to provide more granular access to security alerts as needed. Each security alert (secret scanning, dependency scanning, and code scanning) has both a `Read` permission and a `Write` permission that can be added to a custom role. +[Custom roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization) can be created to provide more granular access to security alerts as needed. Each security alert (secret scanning, dependency scanning, and code scanning) has both a `Read` permission and a `Write` permission that can be added to a custom role. ### Creating and monitoring an exception process There may be times when it is justified to exempt a Pull Request from security scanning, or to exempt a security alert from remediation. In these cases, it is important to have a clear and auditable process for granting these exceptions. -When configuring a Repository Ruleset, you can grant specific Teams, Roles, or GitHub Apps the ability to [bypass the Ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset). This will allow members of the exempted entity to merge code without meeting the conditions of the Ruleset in emergency situations. +When configuring a Repository Ruleset, you can grant specific Teams, Roles, or GitHub Apps the ability to [bypass the Ruleset](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset). This will allow members of the exempted entity to merge code without meeting the conditions of the Ruleset in emergency situations. -When an entity bypasses the requirements of a Ruleset, an event is fired and recorded in the Enterprise's [Audit Log](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise). Similarly, when a security alert is opened, resolved, or dismissed, an event is fired and recorded in the Audit Log. +When an entity bypasses the requirements of a Ruleset, an event is fired and recorded in the Enterprise's [Audit Log](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/audit-log-for-an-enterprise). Similarly, when a security alert is opened, resolved, or dismissed, an event is fired and recorded in the Audit Log. -By configuring a [webhook](https://docs.github.com/en/enterprise-cloud@latest/webhooks/using-webhooks/creating-webhooks#creating-a-global-webhook-for-a-github-enterprise) at the Enterprise level that listens for these events, or by [streaming the Enterprise Audit Log](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise), you can take immediate action, notify relevant stakeholders, or forward the event details to a monitoring tool, like [Microsoft Sentinel](https://learn.microsoft.com/en-us/azure/sentinel/overview?tabs=azure-portal). For more guidance on integrating GitHub Advanced Security with Microsoft Sentinel, follow GitHub's [instructional video](https://www.youtube.com/watch?v=3K664zQSm98). +By configuring a [webhook](https://docs.github.com/enterprise-cloud@latest/webhooks/using-webhooks/creating-webhooks#creating-a-global-webhook-for-a-github-enterprise) at the Enterprise level that listens for these events, or by [streaming the Enterprise Audit Log](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise), you can take immediate action, notify relevant stakeholders, or forward the event details to a monitoring tool, like [Microsoft Sentinel](https://learn.microsoft.com/en-us/azure/sentinel/overview?tabs=azure-portal). For more guidance on integrating GitHub Advanced Security with Microsoft Sentinel, follow GitHub's [instructional video](https://www.youtube.com/watch?v=3K664zQSm98). ## Additional solution detail and trade-offs to consider diff --git a/content/library/application-security/recommendations/managing-dependency-threats.md b/content/library/application-security/recommendations/managing-dependency-threats.md index 71d050e..7e7384b 100644 --- a/content/library/application-security/recommendations/managing-dependency-threats.md +++ b/content/library/application-security/recommendations/managing-dependency-threats.md @@ -174,7 +174,7 @@ When a legitimate package needs lifecycle scripts (like building native modules) ``` {{< callout type="info" >}} -Consider adding your `.npmrc` and `.yarnrc.yml` configurations to a [dotfiles repository](https://docs.github.com/en/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles) to ensure secure defaults follow you across local machines, cloud environments, and GitHub Codespaces. +Consider adding your `.npmrc` and `.yarnrc.yml` configurations to a [dotfiles repository](https://docs.github.com/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles) to ensure secure defaults follow you across local machines, cloud environments, and GitHub Codespaces. {{< /callout >}} #### For GitHub Actions workflows @@ -190,7 +190,7 @@ Configure your workflows to install dependencies with lifecycle scripts disabled ``` {{< callout type="info" >}} -**For high-security environments:** Organizations accepting pull requests from external contributors or with strict compliance requirements can use [larger hosted runners](https://docs.github.com/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners) with custom images that include system-level `.npmrc` and `.yarnrc.yml` files. This enforces script disabling at the runner level, providing defense-in-depth even if workflow configuration is bypassed. +**For high-security environments:** Organizations accepting pull requests from external contributors or with strict compliance requirements can use [larger hosted runners](https://docs.github.com/enterprise-cloud@latest/actions/concepts/runners/larger-runners) with custom images that include system-level `.npmrc` and `.yarnrc.yml` files. This enforces script disabling at the runner level, providing defense-in-depth even if workflow configuration is bypassed. {{< /callout >}} #### When to allow lifecycle scripts @@ -235,7 +235,7 @@ One subtle risk in supply chain attacks is that malicious code might commit chan #### Configure commit signing -[Configure commit signing using a GPG, SSH, or S/MIME key](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). For maximum protection against automated attacks, use a signing method that requires user interaction. Examples include using a passphrase-protected key, biometric authentication, or a hardware security key. +[Configure commit signing using a GPG, SSH, or S/MIME key](https://docs.github.com/authentication/managing-commit-signature-verification/signing-commits). For maximum protection against automated attacks, use a signing method that requires user interaction. Examples include using a passphrase-protected key, biometric authentication, or a hardware security key. {{< callout type="info" >}} **Why user interaction matters:** The key defense here isn't just the cryptographic signature - it's the human verification step. A malicious script running on your machine can access your signing key, but it can't press your fingerprint to the sensor or type your passphrase. This human-in-the-loop requirement is what blocks automated attacks from creating commits on your behalf. @@ -255,7 +255,7 @@ Create a ruleset for your default branch: 1. Navigate to **Settings** → **Rules** → **Rulesets** 2. Add a new ruleset targeting your default branch -3. Examples of [protection rules](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) to configure: +3. Examples of [protection rules](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) to configure: - Require pull requests before merging - Require signed commits - Require status checks to pass (including security scans) @@ -276,7 +276,7 @@ Build trust across the supply chain by establishing cryptographic provenance for For packages you maintain: 1. Link your GitHub repository as a trusted publisher in your package registry settings (npm, PyPI, RubyGems, NuGet, crates.io, etc.) -2. Update your release workflow to use [OIDC authentication](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments) instead of long-lived tokens +2. Update your release workflow to use [OIDC authentication](https://docs.github.com/actions/how-tos/secure-your-work/security-harden-deployments) instead of long-lived tokens 3. Publish with provenance attestations (e.g., `npm publish --provenance`) to create cryptographic proof on the specific commit of the source repository 4. Create [linked artifact storage records](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/linked-artifacts) with the [`actions/attest`](https://github.com/actions/attest) action @@ -304,15 +304,15 @@ Build a comprehensive automated detection system that catches vulnerabilities at **Dependency vulnerabilities:** -Enable [Dependabot security updates](https://docs.github.com/enterprise-cloud@latest/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) to automatically detect vulnerabilities and create pull requests for updates. Consider grouping patch updates for expedited review, assigning security team reviewers, and scheduling daily scans. Use [auto-triage rules](https://docs.github.com/enterprise-cloud@latest/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules) to reduce alert fatigue by automatically dismissing low-risk alerts or alerts for dependencies that don't affect your usage. For comprehensive guidance on managing security alerts at scale, see [Prioritizing security alert remediation](./prioritizing-alerts). +Enable [Dependabot security updates](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-security-updates) to automatically detect vulnerabilities and create pull requests for updates. Consider grouping patch updates for expedited review, assigning security team reviewers, and scheduling daily scans. Use [auto-triage rules](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-auto-triage-rules) to reduce alert fatigue by automatically dismissing low-risk alerts or alerts for dependencies that don't affect your usage. For comprehensive guidance on managing security alerts at scale, see [Prioritizing security alert remediation](./prioritizing-alerts). Add the [dependency review action](https://github.com/actions/dependency-review-action) to your pull request workflows and require it as a status check to prevent potential vulnerabilities from being introduced. Configure it to fail on high-severity vulnerabilities, block problematic licenses, and warn on low [OpenSSF Scorecard](https://securityscorecards.dev/) scores. **Code vulnerabilities and secrets:** -Enable [code scanning](https://docs.github.com/enterprise-cloud@latest/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) to detect vulnerabilities and coding errors in your source code. Configure CodeQL or third-party tools to run on pull requests and block merges when issues are found. +Enable [code scanning](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/code-scanning/code-scanning) to detect vulnerabilities and coding errors in your source code. Configure CodeQL or third-party tools to run on pull requests and block merges when issues are found. -Enable [secret scanning](https://docs.github.com/enterprise-cloud@latest/code-security/secret-scanning/introduction/about-secret-scanning) to detect accidentally committed credentials. Configure push protection to prevent secrets from being pushed in the first place, and establish a response runbook for when alerts are triggered. +Enable [secret scanning](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/secret-security/secret-scanning) to detect accidentally committed credentials. Configure push protection to prevent secrets from being pushed in the first place, and establish a response runbook for when alerts are triggered. **Prioritize alerts with production context:** @@ -357,12 +357,12 @@ The most secure approach (reviewing every dependency change manually and disabli ### Common challenges - **Packages requiring lifecycle scripts**: Some packages (like `node-gyp` for native extensions) legitimately need scripts. Create a documented exception list and use `npm rebuild ` selectively after installation. -- **Alert fatigue**: Dependabot can generate many alerts. Use [auto-triage rules](https://docs.github.com/enterprise-cloud@latest/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules) to dismiss low-risk alerts and prioritize what matters. +- **Alert fatigue**: Dependabot can generate many alerts. Use [auto-triage rules](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-auto-triage-rules) to dismiss low-risk alerts and prioritize what matters. - **Transitive dependencies**: You don't control dependencies of your dependencies. Use `npm audit`, Dependabot, dependency review, and code scanning to gain visibility. Consider replacing direct dependencies that bring in vulnerable transitives. - **Attestations not universally available**: Not all packages support attestations yet. Use attestation availability as one factor in dependency selection and gradually work toward full coverage. - **Keeping lockfiles current**: Lockfiles prevent unexpected updates but can become stale. Regularly update dependencies through Dependabot or scheduled audits to ensure security patches aren't missed while maintaining reproducible builds. - **Breaking changes in security updates**: Security updates sometimes include breaking changes that require code modifications. Establish separate processes for security updates (expedited) vs. feature updates (standard review), and allocate time for security debt remediation. -- **Workflow security risks**: The `pull_request_target` trigger runs with elevated permissions and access to secrets, even for pull requests from forks. Prefer the regular `pull_request` trigger, define least-privilege workflow permissions, and enable [CodeQL workflow analysis](https://docs.github.com/enterprise-cloud@latest/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) to detect vulnerabilities. See the [GitHub Actions 2026 security roadmap](https://github.blog/news-insights/product-news/whats-coming-to-our-github-actions-2026-security-roadmap/) for upcoming capabilities addressing these risks. +- **Workflow security risks**: The `pull_request_target` trigger runs with elevated permissions and access to secrets, even for pull requests from forks. Prefer the regular `pull_request` trigger, define least-privilege workflow permissions, and enable [code scanning](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/code-scanning/code-scanning) to detect vulnerabilities. See the [GitHub Actions 2026 security roadmap](https://github.blog/news-insights/product-news/whats-coming-to-our-github-actions-2026-security-roadmap/) for upcoming capabilities addressing these risks. ## Seeking further assistance @@ -374,14 +374,14 @@ The most secure approach (reviewing every dependency change manually and disabli Specifically, you may find the following links helpful: -- [About Dependabot security updates](https://docs.github.com/enterprise-cloud@latest/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) -- [About dependency review](https://docs.github.com/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review) +- [Dependabot security updates](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependabot-security-updates) +- [Dependency review](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependency-review) - [Signing commits](https://docs.github.com/enterprise-cloud@latest/authentication/managing-commit-signature-verification/signing-commits) - [About rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) - [Verifying npm package provenance](https://docs.npmjs.com/viewing-package-provenance) -- [Using artifact attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations) -- [About supply chain security](https://docs.github.com/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) +- [Using artifact attestations](https://docs.github.com/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations) +- [Supply chain security](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/supply-chain-security) - [Our plan for a more secure npm supply chain](https://github.blog/security/supply-chain-security/our-plan-for-a-more-secure-npm-supply-chain/) - GitHub's response to the Shai-Hulud attack - [The second half of software supply chain security on GitHub](https://github.blog/security/supply-chain-security/the-second-half-of-software-supply-chain-security-on-github/) - Build provenance and artifact attestations - [Securing the open source supply chain: The essential role of CVEs](https://github.blog/security/supply-chain-security/securing-the-open-source-supply-chain-the-essential-role-of-cves/) - Understanding vulnerability data and automation diff --git a/content/library/application-security/recommendations/prioritizing-alerts.md b/content/library/application-security/recommendations/prioritizing-alerts.md index e1292f9..33bf7c6 100644 --- a/content/library/application-security/recommendations/prioritizing-alerts.md +++ b/content/library/application-security/recommendations/prioritizing-alerts.md @@ -127,7 +127,7 @@ For alerts related to your code, like those found by GitHub Advanced Security's - **Severity**: GitHub assigns a severity level (Critical, High, Medium, Low) to each alert, giving you a quick sense of its potential impact. Critical and High severity alerts are a great place to start when cleaning up security tech debt. - **CWE (Common Weakness Enumeration)**: Each alert is also tied to a CWE ID. This is a common way to categorize software weaknesses. Knowing the specific CWE helps you understand the type of vulnerability and often points to well-known attack patterns, informing your remediation strategy. If you have controls in place, like a web application firewall, protecting against a certain class of vulnerability, you might consider it a secondary concern to the vulnerabilities without mitigations. -- **Copilot Autofix Support**: Some code scanning alerts can suggest a fix directly using GitHub Copilot. If an alert has [Copilot Autofix](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning#about-copilot-autofix-for-code-scanning) support, it means the fix might be just a click away. Prioritizing these can lead to quick wins, freeing up your team's time for more complex issues. +- **Copilot Autofix Support**: Some code scanning alerts can suggest a fix directly using GitHub Copilot. If an alert has [Copilot Autofix](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests#working-with-copilot-autofix-suggestions-for-alerts-on-a-pull-request) support, it means the fix might be just a click away. Prioritizing these can lead to quick wins, freeing up your team's time for more complex issues. #### Secret Protection @@ -150,7 +150,7 @@ Keeping your project's dependencies up to date is crucial for security. Dependab While GitHub provides a wealth of metadata to help prioritize security alerts, organizations often possess additional context within their internal systems that can further refine risk assessments. By integrating this unique organizational data, security teams can gain an even more precise understanding of an alert's true impact and prioritize remediation efforts more effectively. -These additional values can be seamlessly added to repositories as [Custom Properties](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) within GitHub. This allows you to combine GitHub's built-in alert metadata with your organization's specific insights. Common examples of custom properties that can significantly enhance alert prioritization include: +These additional values can be seamlessly added to repositories as [Custom Properties](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) within GitHub. This allows you to combine GitHub's built-in alert metadata with your organization's specific insights. Common examples of custom properties that can significantly enhance alert prioritization include: - **Internet facing**: Knowing whether the application it supports is publicly accessible can dramatically elevate the priority of a security alert. An internet-facing vulnerability has a much higher potential for exploitation than one in an internal-only system. - **Regulatory compliance**: If a repository or its associated application falls under specific regulatory compliance mandates (e.g., GDPR, HIPAA, PCI DSS), alerts related to these systems might carry a higher urgency due to potential legal or financial repercussions. @@ -171,10 +171,10 @@ By leveraging the comprehensive metadata now associated with your alerts, you ca The true power of security campaigns lies in their ability to inform downstream users (developers, DevOps teams, and security engineers) of precisely which alerts they should prioritize and by when. When a security campaign is initiated, it will: -- Create a [dedicated dashboard](https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign#viewing-alerts-in-a-security-campaign) that surfaces only the alerts relevant to that campaign, reducing noise and improving focus. -- Automate [notifications](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-managing-security-campaigns#how-developers-know-a-security-campaign-has-started) to the responsible teams or individuals, ensuring accountability. -- Establish [clear deadlines](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-managing-security-campaigns#how-developers-know-a-security-campaign-has-started) or service level objectives (SLOs) for remediation, driving timely action. -- Provide a [centralized tracking mechanism](https://docs.github.com/en/enterprise-cloud@latest/code-security/securing-your-organization/fixing-security-alerts-at-scale/tracking-security-campaigns#tracking-campaigns-across-your-organization) for the progress of the campaign, allowing security leadership to monitor overall risk reduction. +- Create a [security campaign](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign) that surfaces only the relevant alerts, reducing noise and improving focus. +- Configure [notifications](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/creating-managing-security-campaigns#how-developers-know-a-security-campaign-has-started) to the responsible teams or individuals, ensuring accountability. +- Establish [clear deadlines](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/creating-managing-security-campaigns#editing-security-campaign-details) or service level objectives (SLOs) for remediation, driving timely action. +- Provide a [centralized tracking mechanism](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/tracking-security-campaigns#tracking-campaigns-across-your-organization) for the progress of the campaign, allowing security leadership to monitor overall risk reduction. By implementing security campaigns informed by a rich tapestry of metadata, organizations can move beyond reactive alert triage to proactive and targeted remediation efforts. This structured approach ensures that the highest-risk vulnerabilities are addressed first. diff --git a/content/library/application-security/recommendations/securing-developer-workspace.md b/content/library/application-security/recommendations/securing-developer-workspace.md index ce4ece5..a250fcd 100644 --- a/content/library/application-security/recommendations/securing-developer-workspace.md +++ b/content/library/application-security/recommendations/securing-developer-workspace.md @@ -86,8 +86,8 @@ To secure your developer workspaces, consider the following strategies: This article assumes that: -- You have basic understanding of containerization and [development containers](https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) -- You understand Git fundamentals and have experience with [commit signing](https://docs.github.com/en/enterprise-cloud@latest/authentication/managing-commit-signature-verification/about-commit-signature-verification) +- You have basic understanding of containerization and [development containers](https://docs.github.com/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) +- You understand Git fundamentals and have experience with [commit signing](https://docs.github.com/enterprise-cloud@latest/authentication/managing-commit-signature-verification/about-commit-signature-verification) - Your organization has defined security policies and compliance requirements for development environments - Developers have appropriate permissions to configure their development environments within organizational constraints @@ -97,8 +97,8 @@ This article assumes that: Developer workspaces must be protected by strong authentication mechanisms that verify the identity of users before granting access. For GitHub Codespaces and similar environments, this begins with proper authentication to GitHub itself. -- **Enable multi-factor authentication (MFA)**. Require MFA for all developers accessing workspaces. This can be enforced at the [GitHub organization settings](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) or through an identity provider to ensure a consistent security posture. -- **Regular audits**. Periodically review access logs and permissions to identify any unauthorized access attempts or anomalies. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor access patterns. +- **Enable multi-factor authentication (MFA)**. Require MFA for all developers accessing workspaces. This can be enforced at the [GitHub organization settings](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) or through an identity provider to ensure a consistent security posture. +- **Regular audits**. Periodically review access logs and permissions to identify any unauthorized access attempts or anomalies. Use [audit logs](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor access patterns. ### Implement workspace isolation @@ -122,31 +122,31 @@ Securing local development containers, remote containers, and Codespaces ensures In addition to the development container best practices above, Codespaces environments should also follow these additional security recommendations. -- **Leverage Codespaces secrets for sensitive credentials**. Use [Codespaces secrets](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces) to securely store credentials needed during development. These secrets are encrypted and only available to the workspace at runtime, preventing exposure in configuration files or code. To prevent malicious access to secrets stored in the environment, consider adding an additional layer of encryption or using a secrets management tool that requires explicit access. Be aware that organization- and repository-level Codespaces secrets are accessible to anyone with permission to create a Codespace for that repository or within that organization. -- **Restrict repository permissions**. Restrict [Codespaces token permissions](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces) to the minimum necessary for development tasks. Prefer limiting access to `contents: write` for editable repositories, and `contents: read` for repositories that do not require write access. Avoid using wildcards (`*`) to grant access to all repositories. -- **Audit workspace access**. Use [audit logs](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor when Codespaces are created, accessed, or deleted. Look for anomalous patterns that might indicate compromised credentials. -- **Define Codespaces policies**. Use [Codespaces policies](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization) to enforce appropriate security restrictions and to prevent unexpected billing charges. This includes: - - Restrict [allowed base images](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - - Restrict the [idle timeout period](https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) - - Restrict the [available machine types](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) +- **Leverage Codespaces secrets for sensitive credentials**. Use [Codespaces secrets](https://docs.github.com/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) to securely store credentials needed during development. These secrets are encrypted and only available to the workspace at runtime, preventing exposure in configuration files or code. To prevent malicious access to secrets stored in the environment, consider adding an additional layer of encryption or using a secrets management tool that requires explicit access. Be aware that organization- and repository-level Codespaces secrets are accessible to anyone with permission to create a Codespace for that repository or within that organization. +- **Restrict repository permissions**. Restrict [Codespaces token permissions](https://docs.github.com/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces) to the minimum necessary for development tasks. Prefer limiting access to `contents: write` for editable repositories, and `contents: read` for repositories that do not require write access. Avoid using wildcards (`*`) to grant access to all repositories. +- **Audit workspace access**. Use [audit logs](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) to monitor when Codespaces are created, accessed, or deleted. Look for anomalous patterns that might indicate compromised credentials. +- **Define Codespaces policies**. Use [Codespaces policies](https://docs.github.com/codespaces/managing-codespaces-for-your-organization) to enforce appropriate security restrictions and to prevent unexpected billing charges. This includes: + - Restrict [allowed base images](https://docs.github.com/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) + - Restrict the [idle timeout period](https://docs.github.com/enterprise-cloud@latest/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) + - Restrict the [available machine types](https://docs.github.com/enterprise-cloud@latest/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - Restrict the allowed port privacy settings to *Org* (authenticated organization members) to avoid exposing development servers publicly. ### Signed commits -[Commit signing](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) provides cryptographic proof that commits were created by a verified author and have not been tampered with. This is essential for maintaining code integrity and establishing trust in the software supply chain. GitHub supports GPG, SSH, and S/MIME X.509 certificates for commit signing. +[Commit signing](https://docs.github.com/authentication/managing-commit-signature-verification/about-commit-signature-verification) provides cryptographic proof that commits were created by a verified author and have not been tampered with. This is essential for maintaining code integrity and establishing trust in the software supply chain. GitHub supports GPG, SSH, and S/MIME X.509 certificates for commit signing. - **Use signed commits**. Require all developers to sign their commits to ensure authenticity. This makes it easy to validate the origin of code changes and detect unauthorized modifications. - **Authenticate signing requests**. Ensure that signing keys are protected and that users must authenticate to use them. This prevents malicious actors or scripts from creating unauthorized commits by preventing automated signing without user consent. Agents should be configured to use short timeouts, log all access, and require biometric approval. Consider SSH keys stored in hardware tokens or devices that require physical touch when not using development containers or cloud services. -- **Enforce commit signing with rulesets**. Use [organization rulesets](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) to require signed commits on protected branches. This prevents unsigned commits from being merged into critical branches. +- **Enforce commit signing with rulesets**. Use [organization rulesets](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) to require signed commits on protected branches. This prevents unsigned commits from being merged into critical branches. ## Third-party dependencies Third-party dependencies can introduce vulnerabilities into the development environment and the software supply chain. In fact, they are a leading cause of security incidents. It is essential to manage these dependencies carefully to minimize risk. This means reviewing and securing dependencies coming from package managers (like npm, PyPI, Maven, and NuGet), registries (which provide OCI images, Helm charts, and dev container features), OS-level packages (like apt, yum, and apk), and other sources. -- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/en/enterprise-cloud@latest/code-security/getting-started/dependabot-quickstart-guide), to automatically check for updates and vulnerabilities. When a new version is released, review the changelog for security-related fixes before updating. Prefer manual updates over automatic updates to ensure that changes are reviewed. Avoid mutable references. +- **Keep dependencies up to date**. Regularly update third-party libraries and packages to incorporate security patches and improvements. Use dependency management tools, such as [Dependabot](https://docs.github.com/enterprise-cloud@latest/code-security/tutorials/secure-your-dependencies/dependabot-quickstart), to automatically check for updates and vulnerabilities. When a new version is released, review the changelog for security-related fixes before updating. Prefer manual updates over automatic updates to ensure that changes are reviewed. Avoid mutable references. - **Eliminate insecure packages**. Remove or replace packages that are no longer maintained or have known security issues. Vulnerabilities on developer machines can provide access to corporate networks, source code, and other sensitive resources. Use tools like Dependabot to identify and remediate vulnerable and outdated dependencies. Remember that multiple low- and medium-severity vulnerabilities will create a larger attack surface, creating new high- and critical-severity vulnerabilities; avoid accumulating these over time. - **Review all dependencies**. Before adding a new dependency, review its source code, documentation, and community reputation. Look for signs of active maintenance. Avoid packages with excessive permissions or those that execute code during installation without explicit user consent. Continuously review existing dependencies for security risks and remove any that are unnecessary. -- **Restrict automatic code execution during package installation**. Configure package managers to block or prompt for confirmation before executing scripts during dependency installation. This prevents malicious code from running without developer awareness. For example, configure `ignore-scripts=true` in an `.npmrc` file to prevent `npm` from running lifecycle scripts by default. Placing this configuration in the project ensures that this setting applies to everyone that works with the code. In addition, creating this file at the user level (`$HOME/.npmrc` or `%USERPROFILE%\.npmrc`) ensures that you do not automatically run scripts when you restore a project that lacks this configuration. An easy way to apply user-level personalization is to use a [dotfiles](https://dotfiles.github.io/) repository to configure your development machine, [local dev containers](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories), or [Codespaces](https://docs.github.com/en/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). This ensures that your preferred settings are automatically and consistently applied to each development environment. +- **Restrict automatic code execution during package installation**. Configure package managers to block or prompt for confirmation before executing scripts during dependency installation. This prevents malicious code from running without developer awareness. For example, configure `ignore-scripts=true` in an `.npmrc` file to prevent `npm` from running lifecycle scripts by default. Placing this configuration in the project ensures that this setting applies to everyone that works with the code. In addition, creating this file at the user level (`$HOME/.npmrc` or `%USERPROFILE%\.npmrc`) ensures that you do not automatically run scripts when you restore a project that lacks this configuration. An easy way to apply user-level personalization is to use a [dotfiles](https://dotfiles.github.io/) repository to configure your development machine, [local dev containers](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories), or [Codespaces](https://docs.github.com/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). This ensures that your preferred settings are automatically and consistently applied to each development environment. ### Secure AI-assisted development @@ -174,12 +174,12 @@ AI coding assistants can accelerate development, but they also introduce unique Specifically, you may find the following links helpful: -- [About commit signature verification](https://docs.github.com/en/enterprise-cloud@latest/authentication/managing-commit-signature-verification/about-commit-signature-verification) -- [Signing commits](https://docs.github.com/en/enterprise-cloud@latest/authentication/managing-commit-signature-verification/signing-commits) -- [GitHub Codespaces overview](https://docs.github.com/en/enterprise-cloud@latest/codespaces/overview) -- [Introduction to dev containers](https://docs.github.com/en/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) -- [Managing secrets for your codespaces](https://docs.github.com/en/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces) -- [About rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) +- [About commit signature verification](https://docs.github.com/enterprise-cloud@latest/authentication/managing-commit-signature-verification/about-commit-signature-verification) +- [Signing commits](https://docs.github.com/enterprise-cloud@latest/authentication/managing-commit-signature-verification/signing-commits) +- [What are GitHub Codespaces](https://docs.github.com/enterprise-cloud@latest/codespaces/about-codespaces/what-are-codespaces) +- [Introduction to dev containers](https://docs.github.com/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) +- [Managing secrets for your codespaces](https://docs.github.com/enterprise-cloud@latest/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) +- [About rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) - [Safeguarding VS Code against prompt injections](https://github.blog/security/vulnerability-research/safeguarding-vs-code-against-prompt-injections/) ### External resources diff --git a/content/library/architecture/quick-links.md b/content/library/architecture/quick-links.md index f61d214..2225c6e 100644 --- a/content/library/architecture/quick-links.md +++ b/content/library/architecture/quick-links.md @@ -14,11 +14,11 @@ A curated list of resources and tools to enhance productivity across the **Archi - [GitHub Actions for CI/CD](https://github.com/features/actions) - [GitHub Enterprise](https://github.com/enterprise) - [GitHub Engineering Blog](https://github.blog/engineering/) -- [Differences between clustering and high availability in GHES](https://docs.github.com/en/admin/monitoring-managing-and-updating-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha) +- [Differences between clustering and high availability in GHES](https://docs.github.com/enterprise-server@latest/admin/monitoring-and-managing-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha) ## Resiliency -- [High Availability Configuration for GitHub Enterprise Server](https://docs.github.com/en/admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/about-high-availability-configuration) +- [High Availability Configuration for GitHub Enterprise Server](https://docs.github.com/enterprise-server@latest/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration) - [GitHub Backup Utilities](https://github.com/github/backup-utils) - [Azure Reliability quick links](https://learn.microsoft.com/en-us/azure/well-architected/reliability/) - [GitHub Status](https://www.githubstatus.com/) @@ -26,44 +26,44 @@ A curated list of resources and tools to enhance productivity across the **Archi ## Efficiency -- [Caching dependencies to speed up workflows](https://docs.github.com/en/enterprise-cloud@latest/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows) +- [Caching dependencies to speed up workflows](https://docs.github.com/enterprise-cloud@latest/actions/reference/workflows-and-actions/dependency-caching) - [GitHub Codespaces](https://github.com/features/codespaces) - [GitHub CLI](https://cli.github.com/) - [GitHub Actions Marketplace](https://github.com/marketplace?type=actions) ## Disaster Recovery -- [Configuring backups on your instance of GHES](https://docs.github.com/en/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance) +- [Configuring backups on your instance with Backup Utilities](https://docs.github.com/enterprise-server@latest/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance) - [GitHub Backup Utilities](https://github.com/github/backup-utils) - [GitHub Archive Program](https://archiveprogram.github.com/) -- [Backing up and restoring GitHub Enterprise Server with GitHub Actions enabled](https://docs.github.com/en/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled) +- [Backing up and restoring GitHub Enterprise Server with GitHub Actions enabled](https://docs.github.com/enterprise-server@latest/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled) ## Modularity -- [Creating a composite action](https://docs.github.com/en/enterprise-cloud@latest/actions/creating-actions/creating-a-composite-action) -- [GitHub Packages](https://docs.github.com/en/packages/quickstart) -- [GitHub Repositories](https://docs.github.com/en/repositories) -- [GitHub Actions Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) +- [Creating a composite action](https://docs.github.com/enterprise-cloud@latest/actions/tutorials/create-actions/create-a-composite-action) +- [GitHub Packages](https://docs.github.com/packages/quickstart) +- [GitHub Repositories](https://docs.github.com/repositories) +- [GitHub Actions Reusable Workflows](https://docs.github.com/actions/how-tos/reuse-automations/reuse-workflows) ## Interoperability -- [GitHub API](https://docs.github.com/en/rest) -- [GitHub Webhooks](https://docs.github.com/en/enterprise-cloud@latest/webhooks) +- [GitHub API](https://docs.github.com/rest) +- [GitHub Webhooks](https://docs.github.com/enterprise-cloud@latest/webhooks) - [GitHub Integrations Directory](https://github.com/integrations) - [GitHub Actions by the GitHub Expert Services team](https://github.com/actionsdesk) -- [Azure API Management](https://docs.microsoft.com/en-us/azure/api-management/) +- [Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/) ## Simplicity -- [Basic writing and formatting syntax](https://docs.github.com/en/enterprise-cloud@latest/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) -- [Quickstart for GitHub Actions](https://docs.github.com/en/enterprise-cloud@latest/actions/writing-workflows/quickstart) -- [Simplified GitHub Flow](https://docs.github.com/en/enterprise-cloud@latest/get-started/using-github/github-flow) -- [Start your journey with GitHub's pull request workflow](https://docs.github.com/en/enterprise-cloud@latest/get-started/start-your-journey/hello-world) +- [Basic writing and formatting syntax](https://docs.github.com/enterprise-cloud@latest/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) +- [Quickstart for GitHub Actions](https://docs.github.com/enterprise-cloud@latest/actions/get-started/quickstart) +- [Simplified GitHub Flow](https://docs.github.com/enterprise-cloud@latest/get-started/using-github/github-flow) +- [Using GitHub: Hello World](https://docs.github.com/enterprise-cloud@latest/get-started/using-github/hello-world) ## Observability -- [Using workflow run logs](https://docs.github.com/en/enterprise-cloud@latest/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs) -- [Reviewing the audit log for your organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) -- [About insights for Projects](https://docs.github.com/en/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects) -- [Azure Monitor](https://docs.microsoft.com/en-us/azure/azure-monitor/) -- [Monitoring and troubleshooting workflows](https://docs.github.com/en/enterprise-cloud@latest/actions/monitoring-and-troubleshooting-workflows) +- [Using workflow run logs](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/monitor-workflows/use-workflow-run-logs) +- [Reviewing the audit log for your organization](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) +- [About insights for Projects](https://docs.github.com/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects) +- [Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/) +- [Monitoring workflows](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/monitor-workflows) diff --git a/content/library/architecture/recommendations/deploying-actions-runner-controller.md b/content/library/architecture/recommendations/deploying-actions-runner-controller.md index a2f8592..81487fe 100644 --- a/content/library/architecture/recommendations/deploying-actions-runner-controller.md +++ b/content/library/architecture/recommendations/deploying-actions-runner-controller.md @@ -70,7 +70,7 @@ See our CONTRIBUTING doc for submission details and additional writing style gui ## Scenario overview -When making the decision to deploy self-hosted runners for GitHub Actions, organizations must consider how to best manage and scale those runners. The [Actions Runner Controller (ARC)](https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/runners/actions-runner-controller) is an open-source project that provides a Kubernetes-based solution for deploying and managing self-hosted runners. This article outlines recommendations for deploying ARC in a scalable and maintainable manner. +When making the decision to deploy self-hosted runners for GitHub Actions, organizations must consider how to best manage and scale those runners. The [Actions Runner Controller (ARC)](https://docs.github.com/enterprise-cloud@latest/actions/concepts/runners/actions-runner-controller) is an open-source project that provides a Kubernetes-based solution for deploying and managing self-hosted runners. This article outlines recommendations for deploying ARC in a scalable and maintainable manner. {{< callout type="warning" >}} Users are responsible for the security of their clusters and the workloads running on them. Securing a Kubernetes cluster, the underlying nodes, and the network resources is a complex task that requires expert-level knowledge. Ensure appropriate network segmentation and monitoring are in place, and follow zero-trust principles when granting access to resources. ARC does not provide any additional built-in security features beyond those provided by Kubernetes and the underlying infrastructure. @@ -116,7 +116,7 @@ ARC does not support preemption or spot instances, and it assumes that once a ru While the default runner image provided by GitHub is suitable for many use cases, creating a custom image is essential for production workloads. It minimizes job startup and execution times, reduces the potential for rate limiting, and ensures that required tools and dependencies are available. - **Review the core requirements.** - All self-hosted runner solutions must meet the [documented requirements](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners). + All self-hosted runner solutions must meet the [documented requirements](https://docs.github.com/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners). - **Create an Actions archive cache.** Review how GitHub-hosted runners [create an archive cache](https://www.kenmuse.com/blog/building-github-actions-runner-images-with-an-action-archive-cache/) with the most frequently used Actions to speed up job execution and avoid repeated downloads. @@ -125,7 +125,7 @@ While the default runner image provided by GitHub is suitable for many use cases Review the steps for implementing a [tool cache](https://www.kenmuse.com/blog/building-github-actions-runner-images-with-a-tool-cache/) to make platform tools and binaries available locally on the runner. This eliminates the need to download the tools during the job, reducing execution time and network traffic. - **Keep the runner version up-to-date.** - The runner image should be regularly updated to take advantage of the latest features and security fixes. If you're using GitHub Enterprise Cloud, self-hosted runners cannot be more than [30 days](https://docs.github.com/en/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners#runner-software-updates-on-self-hosted-runners) behind the latest version. If you're using GitHub Enterprise Server, you must use *at least* the version provided with your instance. Runners are generally backwards compatible with older versions of the server platform. + The runner image should be regularly updated to take advantage of the latest features and security fixes. If you're using GitHub Enterprise Cloud, self-hosted runners cannot be more than [30 days](https://docs.github.com/enterprise-cloud@latest/actions/reference/runners/self-hosted-runners#runner-software-updates-on-self-hosted-runners) behind the latest version. If you're using GitHub Enterprise Server, you must use *at least* the version provided with your instance. Runners are generally backwards compatible with older versions of the server platform. ### Configure Kubernetes for ARC @@ -184,7 +184,7 @@ While the default runner image provided by GitHub is suitable for many use cases Tools like Flex and ArgoCD are not supported or recommended. - **Use the latest version of ARC.** - Regularly update ARC to the latest version (carefully following the [published instructions](https://docs.github.com/en/enterprise-cloud@latest/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets#upgrading-arc)) to benefit from new features and security patches. This is also required to ensure organizations are on a supported release. Avoid using `helm upgrade`, Flex, ArgoCD, or other approaches that do not follow the documented upgrade process. + Regularly update ARC to the latest version (carefully following the [published instructions](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets#upgrading-arc)) to benefit from new features and security patches. This is also required to ensure organizations are on a supported release. Avoid using `helm upgrade`, Flex, ArgoCD, or other approaches that do not follow the documented upgrade process. - **Avoid non-Linux runners.** ARC is optimized for Linux-based runners. GitHub does not support using ARC with Windows or macOS based runners, and Windows containers have [additional limitations and considerations](https://kubernetes.io/docs/concepts/windows/intro/). @@ -231,7 +231,7 @@ ARC scales by requesting pods in Kubernetes according to the provided `template. ### Docker-in-Docker (DinD) considerations -[Docker-in-Docker](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets#using-docker-in-docker-mode) uses a `privileged` native sidecar container running as `root` to host the Docker daemon and manage the containers. This configuration supports containerized Actions and building/runner images using the Docker command line. +[Docker-in-Docker](https://docs.github.com/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets#using-docker-in-docker-mode) uses a `privileged` native sidecar container running as `root` to host the Docker daemon and manage the containers. This configuration supports containerized Actions and building/runner images using the Docker command line. {{< callout type="info" >}} Docker-in-Docker must be run as a `privileged` container to have permission to create and manage the containers; the runner container should remain unprivileged. This is required even when using the `docker:dind-rootless` image to run Docker as a non-root user. @@ -251,7 +251,7 @@ Docker-in-Docker must be run as a `privileged` container to have permission to c ### Kubernetes mode considerations -[Kubernetes mode](https://docs.github.com/en/enterprise-cloud@latest/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets#using-kubernetes-mode) uses [container hooks](https://github.com/actions/runner-container-hooks) to enable the runner to create a worker pod using the Kubernetes API to host the job and service containers. This requires the runner pod to have elevated privileges. Using the `containerMode` `kubernetes` requires a persistent volume claim (PVC) for file storage. Alternatively, [`kubernetes-novolume`](https://docs.github.com/en/enterprise-cloud@latest/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets#configuring-kubernetes-mode-with-container-lifecycle-hooks) can be used. Kubernetes APIs are used to manage files rather than PVCs, requiring the runner container to run as `root` and trading performance for easier configuration. +[Kubernetes mode](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets#using-kubernetes-mode) uses [container hooks](https://github.com/actions/runner-container-hooks) to enable the runner to create a worker pod using the Kubernetes API to host the job and service containers. This requires the runner pod to have elevated privileges. Using the `containerMode` `kubernetes` requires a persistent volume claim (PVC) for file storage. Alternatively, [`kubernetes-novolume`](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets#configuring-kubernetes-mode-with-container-lifecycle-hooks) can be used. Kubernetes APIs are used to manage files rather than PVCs, requiring the runner container to run as `root` and trading performance for easier configuration. {{< callout type="info" >}} This configuration requires the runner pod to run with elevated privileges to create and manage pods within the cluster, giving it access to pods and secrets using the Kubernetes APIs. When the `containerMode` is specified, ARC will create a [role](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/templates/kube_mode_role.yaml), [service account](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/templates/kube_mode_serviceaccount.yaml), and [binding](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/templates/kube_mode_role_binding.yaml) for this purpose. When a custom `template.spec` is provided, these resources are not created automatically and must be created and managed separately. @@ -284,8 +284,8 @@ Kubernetes does not contain a Docker runtime, so this mode does not support Acti Specifically, you may find the following links helpful: -- [Actions Runner Controller](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller) -- [Deploying runner scale sets with Actions Runner Controller](https://docs.github.com/en/actions/tutorials/use-actions-runner-controller/deploy-runner-scale-sets) +- [Actions Runner Controller](https://docs.github.com/actions/concepts/runners/actions-runner-controller) +- [Deploying runner scale sets with Actions Runner Controller](https://docs.github.com/actions/how-tos/manage-runners/use-actions-runner-controller/deploy-runner-scale-sets) ### External Resources diff --git a/content/library/architecture/recommendations/expanding-enterprise-custom-agents-context.md b/content/library/architecture/recommendations/expanding-enterprise-custom-agents-context.md index da18661..be76acd 100644 --- a/content/library/architecture/recommendations/expanding-enterprise-custom-agents-context.md +++ b/content/library/architecture/recommendations/expanding-enterprise-custom-agents-context.md @@ -100,7 +100,7 @@ This article provides a prescriptive approach to expanding the available context Before implementing this solution, the following must be in place: - **GitHub Enterprise Custom Agents enabled.** Your organization has [GitHub Enterprise Custom Agents](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) configured and the `.github-private` repository created. -- **Model Context Protocol (MCP) configured.** The [Model Context Protocol](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/agents/coding-agent/mcp-and-coding-agent) is enabled in your GitHub Enterprise settings, providing access to the GitHub MCP server. +- **Model Context Protocol (MCP) configured.** The [Model Context Protocol](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent) is enabled in your GitHub Enterprise settings, providing access to the GitHub MCP server. - **Administrative access.** You have admin access to the `.github-private` repository and permissions to configure environment secrets in target repositories. - **GitHub Enterprise Cloud.** This solution is designed for GitHub Enterprise Cloud, including EMU and Data Residency environments. It leverages features specific to these platforms. - **Understanding of custom agents.** Team members responsible for implementing this solution understand how custom agents are defined and invoked. @@ -249,7 +249,7 @@ This configuration must be repeated for each repository where you want to use cu Test that your custom agent can successfully access the expanded context: 1. Navigate to a repository where you configured the `copilot` environment secret -2. [Assign a task](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#asking-copilot-to-create-a-pull-request-from-the-agents-tab-or-panel) to your custom agent using the GitHub Copilot interface +2. [Assign a task](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions) to your custom agent using the GitHub Copilot interface 3. Monitor the agent's activity in the [agent panel](https://github.com/copilot/agents) 4. Look for log messages indicating **"Get file contents from GitHub"** or similar 5. Verify the agent's responses reflect the guidance from your knowledge files @@ -430,10 +430,10 @@ Use kebab-case for filenames: `secure-coding-standards.md` Specifically, you may find the following links helpful: - [Prepare for GitHub Enterprise Custom Agents](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) -- [Model Context Protocol (MCP) and Coding Agent](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/agents/coding-agent/mcp-and-coding-agent) -- [Creating a personal access token](https://docs.github.com/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) -- [Using environments for deployment](https://docs.github.com/enterprise-cloud@latest/actions/deployment/targeting-different-environments/using-environments-for-deployment) -- [Customizing the built-in GitHub MCP server](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#customizing-the-built-in-github-mcp-server) +- [Model Context Protocol (MCP) and GitHub Copilot cloud agent](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent) +- [Managing your personal access tokens](https://docs.github.com/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) +- [Managing environments for deployment](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) +- [Customizing the built-in GitHub MCP server](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers#customizing-the-built-in-github-mcp-server) ### External Resources diff --git a/content/library/architecture/recommendations/hosted-runner-private-networking.md b/content/library/architecture/recommendations/hosted-runner-private-networking.md index 6a965d2..267c8da 100644 --- a/content/library/architecture/recommendations/hosted-runner-private-networking.md +++ b/content/library/architecture/recommendations/hosted-runner-private-networking.md @@ -64,9 +64,9 @@ github: ## Scenario overview -[GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) are a cost-effective, secure, and low maintenance option for running your [GitHub Actions](https://docs.github.com/en/actions) workflows. Hosted runners are managed by GitHub, run on GitHub-owned infrastructure, and have access to the public internet by default. +[GitHub-hosted runners](https://docs.github.com/actions/concepts/runners/github-hosted-runners) are a cost-effective, secure, and low maintenance option for running your [GitHub Actions](https://docs.github.com/actions) workflows. Hosted runners are managed by GitHub, run on GitHub-owned infrastructure, and have access to the public internet by default. -Many customers need to access private resources from their GitHub Actions workflows to perform actions such as deploying software to private infrastructure or using private package managers. Accessing these resources is not possible with the default GitHub-hosted runner configurations without enabling access to the internet. This article presents a few options for enabling GitHub-hosted runners to access private resources, and focuses on the [Azure Private Networking](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) feature which is the most comprehensive solution for private network access. +Many customers need to access private resources from their GitHub Actions workflows to perform actions such as deploying software to private infrastructure or using private package managers. Accessing these resources is not possible with the default GitHub-hosted runner configurations without enabling access to the internet. This article presents a few options for enabling GitHub-hosted runners to access private resources, and focuses on the [Azure Private Networking](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) feature which is the most comprehensive solution for private network access. ## Potential Solutions @@ -77,24 +77,24 @@ GitHub offers a few potential solutions to enable access to private resources: 1. Using Azure Private Networking {{< callout type="info" >}} -Some of these features require the use of GitHub-hosted larger runners. GitHub offers both [standard](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) and [larger](https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners) hosted runners. [GitHub-hosted larger runners](https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners) are provisioned specifically for your enterprise or organization, as opposed to standard runners which are common pools of runners used across all of GitHub. Larger runners offer a few capabilities that aren't available on standard runners for an added cost. +Some of these features require the use of GitHub-hosted larger runners. GitHub offers both [standard](https://docs.github.com/actions/concepts/runners/github-hosted-runners) and [larger](https://docs.github.com/enterprise-cloud@latest/actions/concepts/runners/larger-runners) hosted runners. GitHub-hosted larger runners are provisioned specifically for your enterprise or organization, as opposed to standard runners which are common pools of runners used across all of GitHub. Larger runners offer a few capabilities that aren't available on standard runners for an added cost. {{< /callout >}} ### Using Static IP Addresses -[Static IP addresses on larger runners](https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#creating-static-ip-addresses-for-larger-runners) establish public IP CIDR blocks that will contain the IP addresses of your larger runners. This allows you to configure your private networking and firewalls to enable inbound connectivity from only your larger runners without enabling access from any arbitrary sources. +[Static IP addresses on larger runners](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/larger-runners/manage-larger-runners#creating-static-ip-addresses-for-larger-runners) establish public IP CIDR blocks that will contain the IP addresses of your larger runners. This allows you to configure your private networking and firewalls to enable inbound connectivity from only your larger runners without enabling access from any arbitrary sources. Static IP addresses are a quick and relatively easy way to enable Actions workflows on GitHub-hosted runners to access your private resources, with the obvious disadvantage of requiring inbound access from a set of known, static, public IP addresses. You may also need to configure mechanisms such as port forwarding or network address translation to reach private resources from outside your network. While static IP addresses may work for some organizations, these tradeoffs may not be acceptable for others. ### Using an API Gateway with OIDC -[Using an API Gateway with OIDC](https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc) involves standing up an API Gateway on the edge of your network (or using an existing API Gateway) and using OIDC tokens to authenticate requests from GitHub Actions to your API Gateway. This solution provides a secure connection between the hosted runner and your private services and can be used with standard GitHub-hosted runners, or combined with static IP addresses on larger runners to further restrict traffic to the API Gateway. +[Using an API Gateway with OIDC](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/github-hosted-runners/connect-to-a-private-network/connect-with-oidc) involves standing up an API Gateway on the edge of your network (or using an existing API Gateway) and using OIDC tokens to authenticate requests from GitHub Actions to your API Gateway. This solution provides a secure connection between the hosted runner and your private services and can be used with standard GitHub-hosted runners, or combined with static IP addresses on larger runners to further restrict traffic to the API Gateway. This pattern is most useful when the private resources you need to access from your Actions workflows are services with their own APIs, as opposed to direct access to network endpoints. The major disadvantage is that you must have an API Gateway and it must be reachable from the public internet, at least from the CIDR blocks of your larger runner static IPs if you choose to use larger runners. As with static IP addresses, this solution may work for some organizations but may not fit the security needs of all. ### Using Azure Private Networking -[Azure private networking](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) allows you to maintain complete control over the networking configuration of your GitHub-hosted larger runners. Azure private networking enables larger runners to privately connect to your network and resources through an Azure Virtual Network, without opening ports or enabling access to those resources from the public internet. This not only enables private access to Azure resources; when combined with Azure [ExpressRoute](https://azure.microsoft.com/en-us/products/expressroute) or [VPN Gateway](https://azure.microsoft.com/en-us/products/vpn-gateway) it can also enable access to resources in your private on-premise networks as well. +[Azure private networking](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) allows you to maintain complete control over the networking configuration of your GitHub-hosted larger runners. Azure private networking enables larger runners to privately connect to your network and resources through an Azure Virtual Network, without opening ports or enabling access to those resources from the public internet. This not only enables private access to Azure resources; when combined with Azure [ExpressRoute](https://azure.microsoft.com/en-us/products/expressroute) or [VPN Gateway](https://azure.microsoft.com/en-us/products/vpn-gateway) it can also enable access to resources in your private on-premise networks as well. The disadvantages of this approach are that an Azure presence is required and the configuration requires some access permissions in your Azure subscription. These requirements are covered in detail below. @@ -104,7 +104,7 @@ The disadvantages of this approach are that an Azure presence is required and th Azure private networking leverages an Azure pattern known as VNET injection to deploy the GitHub-hosted runner's network interface card (NIC) into your private Azure VNET, while the runner VM resides in GitHub-owned infrastructure. The result is that you are in complete control of the runner's network access controls. -This diagram and the other content from the [About Azure private networking](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) documentation describes the general architecture and how this feature is implemented in GitHub and Azure. There is no need to repeat that documentation here, however below we touch on a few aspects that may be of particular interest to those using this feature. +This diagram and the other content from the [About Azure private networking](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) documentation describes the general architecture and how this feature is implemented in GitHub and Azure. There is no need to repeat that documentation here, however below we touch on a few aspects that may be of particular interest to those using this feature. ![Architecture](./assets/actions-vnet-injected-larger-runners-architecture.webp) @@ -120,7 +120,7 @@ The customer will be responsible for all of the typical Azure costs associated w ### Deployment -Deploying the Azure private networking feature involves creating or updating a handful of Azure resources, adding a hosted compute networking configuration in your GitHub enterprise or organization, and associating that networking configuration with a new or existing runner group. The [configuration documentation](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise) provides instructions and sample resources to facilitate this deployment. The process to create and configure the required Azure and GitHub resources can be summarized as follows: +Deploying the Azure private networking feature involves creating or updating a handful of Azure resources, adding a hosted compute networking configuration in your GitHub enterprise or organization, and associating that networking configuration with a new or existing runner group. The [configuration documentation](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise) provides instructions and sample resources to facilitate this deployment. The process to create and configure the required Azure and GitHub resources can be summarized as follows: 1. Register the `GitHub.Network` Azure resource provider in your Azure subscription 1. Create a suitable Azure VNET subnet and delegate it to the `GitHub.Network/networkSettings` resource type. This delegation is what enables the `GitHub.Network` resource provider to deploy the runner NICs into your VNET. There are some required network connectivity rules to enable the runner to operate properly, e.g. connectivity to some GitHub and Azure services that are used at runtime. We will cover these connectivity requirements and the options for facilitating those later. @@ -132,13 +132,13 @@ Once these steps are completed, new runners that are created in the runner group The documentation provides the following sample resources: -1. A [bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) [file that defines the Azure Network Security Group (NSG)](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#prerequisites) and its network security rules. The rules defined here are only an example and are considered to be the +1. A [bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) [file that defines the Azure Network Security Group (NSG)](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#prerequisites) and its network security rules. The rules defined here are only an example and are considered to be the minimum for basic functionality of the runner and its ability to access GitHub services. Your workflows may require additional security rules to enable connectivity to your desired resources, be they private or public. -1. A [bash script](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#2-use-a-script-to-configure-your-azure-resources) +1. A [bash script](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#2-use-a-script-to-configure-your-azure-resources) that uses the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/) to perform the required Azure resource operations. {{< callout type="info" >}} -The number of available IP addresses in your subnet should meet or exceed the `Maximum concurrency` setting of the larger runner configuration that will be deployed into the subnet. The [Maximum concurrency setting](https://docs.github.com/en/enterprise-cloud@latest/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners#autoscaling-larger-runners) is available in GitHub on the larger runner configuration, and its value is an upper bound on the number of concurrent runner VMs that will be deployed for this larger runner. If the available IP addresses in the Azure subnet do not meet or exceed the maximum concurrency setting then GitHub will not be able to scale the larger runner up to the desired maximum concurrency. In some cases GitHub will scale the runner over the `Maximum concurrency` value by 20%, for example if some runners are slow or unable to come online, so to be safe we recommend the available IP addresses be 20% more than the `Maximum concurrency` value. The number of available IP addresses in your Azure subnet is defined by the CIDR blocks used for the VNET address space and subnet address prefix. +The number of available IP addresses in your subnet should meet or exceed the `Maximum concurrency` setting of the larger runner configuration that will be deployed into the subnet. The [Maximum concurrency setting](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/manage-runners/larger-runners/manage-larger-runners#configuring-autoscaling-for-larger-runners) is available in GitHub on the larger runner configuration, and its value is an upper bound on the number of concurrent runner VMs that will be deployed for this larger runner. If the available IP addresses in the Azure subnet do not meet or exceed the maximum concurrency setting then GitHub will not be able to scale the larger runner up to the desired maximum concurrency. In some cases GitHub will scale the runner over the `Maximum concurrency` value by 20%, for example if some runners are slow or unable to come online, so to be safe we recommend the available IP addresses be 20% more than the `Maximum concurrency` value. The number of available IP addresses in your Azure subnet is defined by the CIDR blocks used for the VNET address space and subnet address prefix. {{< /callout >}} ### Customizing the Deployment @@ -146,7 +146,7 @@ The number of available IP addresses in your subnet should meet or exceed the `M The instructions and resources in the documentation are an example of how to deploy Azure private networking, they are not the only way to do so nor is it required to use bicep, bash, or any other particular technology. You may choose to customize your Azure private networking configuration and deployment in a number of ways: 1. Defining all, or at least more, of the required Azure resources in `bicep` instead of `az` CLI commands. -1. Using [terraform](https://www.terraform.io/) instead of `bicep`/`az` CLI. Below we will discuss using an open source GitHub terraform module, created by GitHub engineers, to deploy the resources. +1. Using [terraform](https://developer.hashicorp.com/terraform) instead of `bicep`/`az` CLI. Below we will discuss using an open source GitHub terraform module, created by GitHub engineers, to deploy the resources. 1. Using [Azure Firewall](https://learn.microsoft.com/en-us/azure/firewall/overview) instead of NSGs to implement the VNET network security rules. Azure Firewall is a more comprehensive firewall product that, among other advanced functionality, allows you to specify network security rules in terms of host names instead of IP addresses. Many of the CIDR blocks in the sample bicep file are associated with the same GitHub service, so the equivalent security rules expressed in terms of host names can be considerably simpler and easier to maintain. Using Azure Firewwall incurs added costs in your Azure subscription, but if your organization already has an Azure networking presence then you are most likely already securing your virtual networks with Azure Firewall or another @@ -163,10 +163,10 @@ The GitHub hosted runners will be deployed into the same Azure region as your Vi Azure Private Networking has a few limitations and security requirements that are worth mentioning: -1. The feature is only available in a subset of Azure regions. See the [About supported regions](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise#about-supported-regions) documentation for the complete list. If you are using [GitHub Enterprise Cloud with Data Residency (GHE)](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency) then pay special attention to the note about [supported regions for GHE](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/network-details-for-ghecom#supported-regions-for-azure-private-networking). The documentation also provides a link to the GitHub forum where you can request support for a new region. +1. The feature is only available in a subset of Azure regions. See the [About supported regions](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise#about-supported-regions) documentation for the complete list. If you are using [GitHub Enterprise Cloud with Data Residency (GHE)](https://docs.github.com/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency) then pay special attention to the note about [supported regions for GHE](https://docs.github.com/enterprise-cloud@latest/admin/data-residency/network-details-for-ghecom#supported-regions-for-azure-private-networking). The documentation also provides a link to the GitHub forum where you can request support for a new region. 1. MacOS runners are not supported. 1. Registering the `GitHub.Network` resource provider in your Azure subscription will create two enterprise applications: `GitHub CPS Network Service` and `GitHub Actions API`. These are required for the GitHub services to perform the necessary operations in your Azure VNET. -1. The above enterprise applications are granted certain permissions which are documented in [About the GitHub Actions service permissions](https://docs.github.com/en/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise#about-the-github-actions-service-permissions). These are the permissions required for the two enterprise applications to manage the delegated subnet and deploy the runner NICs. +1. The above enterprise applications are granted certain permissions which are documented in [About the GitHub Actions service permissions](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise#about-the-github-actions-service-permissions). These are the permissions required for the two enterprise applications to manage the delegated subnet and deploy the runner NICs. {{< callout type="info" >}} GitHub can only access subnets that have been delegated to the `GitHub.Network/networkSettings` resource type. Even though the permissions to the `GitHub.Network` resource provider are granted at the Subscription level, the Azure services that facilitate the VNET injection pattern ensure that the GitHub resource type can only access subnets delegated to it. GitHub resources and services cannot access any other parts of your Azure infrastructure. diff --git a/content/library/architecture/recommendations/scaling-git-repositories/large-git-repositories.md b/content/library/architecture/recommendations/scaling-git-repositories/large-git-repositories.md index 88ace86..c87e2a6 100644 --- a/content/library/architecture/recommendations/scaling-git-repositories/large-git-repositories.md +++ b/content/library/architecture/recommendations/scaling-git-repositories/large-git-repositories.md @@ -126,7 +126,7 @@ This section defines the key design strategies that a company could employ to im ### 4. **Improved Cloning and Fetching Mechanisms** -- **Shallow Clones**: Encouraging the use of shallow clones (`git clone --depth=1`) or partial clones ([`git clone --filter=blob:none` or `--filter=blob:limit=`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt)) to minimize the amount of data cloned, which speeds up the initial setup for new developers and reduces bandwidth usage. +- **Shallow Clones**: Encouraging the use of shallow clones (`git clone --depth=1`) or partial clones ([`git clone --filter=blob:none` or `--filter=blob:limit=`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterfilter-spec)) to minimize the amount of data cloned, which speeds up the initial setup for new developers and reduces bandwidth usage. - **Shallow Directory Structure**: Deeply-nested directory structures increase the number of tree and blob objects created over time, which can lead to repository bloat and reduce the efficiency of object packing and delta compression during Git operations. - **Fetch Often**: The further the client and server drift from one another, the longer each push will take. Fetching regularly can reduce the time it takes to complete a push. @@ -330,13 +330,13 @@ If you have questions or need help implementing the proposed repository architec #### 1. **GitHub Support** - **GitHub Support Portal**: Visit the [GitHub Support Portal](https://support.github.com) for a comprehensive collection of articles, tutorials, and guides on using GitHub features and services. -- **GitHub Community Forum**: Join the [GitHub Community Forum](https://github.community) to ask questions, share knowledge, and connect with other GitHub users. It's a great place to get advice and solutions from experienced developers. +- **GitHub Community Forum**: Join the [GitHub Community Forum](https://github.com/orgs/community/discussions) to ask questions, share knowledge, and connect with other GitHub users. It's a great place to get advice and solutions from experienced developers. - **GitHub Support Ticket**: If you need direct assistance from GitHub’s support team, you can submit a ticket through the [GitHub Support Portal](https://support.github.com). Various support plans are available, including free, premium, and enterprise options, depending on your needs. #### 2. **GitHub Expert Services** -- **Consulting Services**: GitHub Expert Services offers expert consulting to help you optimize your GitHub workflows, implement best practices, and ensure successful deployment of your repository architecture strategy. Learn more about these services at [GitHub Expert Services](https://services.github.com). -- **Training and Workshops**: GitHub provides training sessions and workshops to help your team get up to speed with GitHub tools and features. These can be customized to address specific needs and use cases. Learn more about these services at [GitHub Expert Services](https://services.github.com). +- **Consulting Services**: GitHub Expert Services offers expert consulting to help you optimize your GitHub workflows, implement best practices, and ensure successful deployment of your repository architecture strategy. Learn more about these services at [GitHub Expert Services](https://github.com/services/). +- **Training and Workshops**: GitHub provides training sessions and workshops to help your team get up to speed with GitHub tools and features. These can be customized to address specific needs and use cases. Learn more about these services at [GitHub Expert Services](https://github.com/services/). #### 3. **GitHub Partner Community** @@ -349,7 +349,7 @@ If you have questions or need help implementing the proposed repository architec #### 5. **Local and Virtual Meetups** -- **GitHub Events**: Attend GitHub-hosted events such as GitHub Universe, GitHub Satellite, and local meetups to network with other developers, learn from experts, and stay updated on the latest GitHub features and trends. Check out upcoming events at [GitHub Events](https://github.com/events). +- **GitHub Events**: Attend GitHub-hosted events such as GitHub Universe, GitHub Satellite, and local meetups to network with other developers, learn from experts, and stay updated on the latest GitHub features and trends. Check out upcoming events at [GitHub Events](https://github.com/resources/events). By leveraging these resources and support options, you can gain the knowledge and assistance needed to successfully implement and optimize your repository architecture strategy on GitHub. diff --git a/content/library/architecture/recommendations/scaling-git-repositories/when-to-use-git-lfs.md b/content/library/architecture/recommendations/scaling-git-repositories/when-to-use-git-lfs.md index 79a38e1..4c48579 100644 --- a/content/library/architecture/recommendations/scaling-git-repositories/when-to-use-git-lfs.md +++ b/content/library/architecture/recommendations/scaling-git-repositories/when-to-use-git-lfs.md @@ -165,11 +165,11 @@ When comparing the clone sizes above, `Repo 1` benefits more from having a shall This is not the case for `Repo 2`, however. The files don't compress well in this case, so removing them from the repository has a net positive effect on the overall experience. The clone times between `shallow clone` and `lfs pull` are roughly the same, but the impact on the git server, as well as the enumerating of objects on the client is an overall net positive. LFS for `Repo 2` is highly recommended because of the characteristics of the repository. -_Note: To optimize the experience, using `shallow clone` and `partial clone` will greatly improve the developer experience when working with monorepos and extensive history. See [Get up to speed with partial clone and shallow clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) for proper guidance._ +_Note: To optimize the experience, using `shallow clone` and `partial clone` will greatly improve the developer experience when working with monorepos and extensive history. See [Get up to speed with partial clone and shallow clone](https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/) for proper guidance._ #### Repositories with excessively large text files that change often -As noted above, text files compress well (see the bottom for how to test compression of a file). If the file changes often, git will be able to handle the compression and decompression of these files. There will, of course, be an impact on certain git operations (i.e. git status), but if they change often you have additional bandwidth and storage considerations that may negate the benefit of LFS (see example above). By keeping up with the latest version of Git you can take advantage of some of the newer features that reduce friction with geometric repacking, merge-ort, or a number of new features released in Git [v2.33](https://github.blog/2021-08-16-highlights-from-git-2-33), [v2.34](https://github.blog/2021-11-15-highlights-from-git-2-34) and [v2.35](https://github.blog/2022-01-24-highlights-from-git-2-35). +As noted above, text files compress well (see the bottom for how to test compression of a file). If the file changes often, git will be able to handle the compression and decompression of these files. There will, of course, be an impact on certain git operations (i.e. git status), but if they change often you have additional bandwidth and storage considerations that may negate the benefit of LFS (see example above). By keeping up with the latest version of Git you can take advantage of some of the newer features that reduce friction with geometric repacking, merge-ort, or a number of new features released in Git [v2.33](https://github.blog/open-source/git/highlights-from-git-2-33/), [v2.34](https://github.blog/open-source/git/highlights-from-git-2-34/) and [v2.35](https://github.blog/open-source/git/highlights-from-git-2-35/). #### Shallow clone workflows diff --git a/content/library/collaboration/quick-links.md b/content/library/collaboration/quick-links.md index 52b9fee..e887e51 100644 --- a/content/library/collaboration/quick-links.md +++ b/content/library/collaboration/quick-links.md @@ -11,9 +11,9 @@ A curated list of resources and tools to enhance **Collaboration** within your o ## Effective Communication -- [Communicating on GitHub](https://docs.github.com/en/enterprise-cloud@latest/get-started/using-github/communicating-on-github) +- [Communicating on GitHub](https://docs.github.com/enterprise-cloud@latest/get-started/using-github/communicating-on-github) - [Microsoft Teams](https://www.microsoft.com/en-us/microsoft-teams/group-chat-software) -- [Communicate effectively using Microsoft Teams](https://www.linkedin.com/learning/microsoft-teams-essential-training-23397024/communicate-effectively-with-microsoft-teams) +- [Communicate effectively with Microsoft Teams](https://www.linkedin.com/learning/microsoft-teams-essential-training-23929395/communicate-effectively-with-microsoft-teams) ## Inclusivity @@ -36,5 +36,4 @@ A curated list of resources and tools to enhance **Collaboration** within your o ## Flexibility - [GitHub Engineering](https://github.blog/engineering/) -- [Grow your cognitive flexibility](https://learn.microsoft.com/en-us/training/modules/grow-cognitive-flexibility/) - [GitHub Marketplace](https://github.com/marketplace) diff --git a/content/library/collaboration/recommendations/applying-devops-methodology.md b/content/library/collaboration/recommendations/applying-devops-methodology.md index ecb458d..2bb4381 100644 --- a/content/library/collaboration/recommendations/applying-devops-methodology.md +++ b/content/library/collaboration/recommendations/applying-devops-methodology.md @@ -70,7 +70,7 @@ github: - partners --- -DevOps methodology revolutionizes how development and operations teams work together to deliver software quickly and reliably. This article delves into the key principles and evolving roles within DevOps, helping organizations enhance productivity and collaboration. For a deeper dive into DevOps practices and resources, be sure to check out the extensive materials available on [GitHub's DevOps Resources](https://github.com/resources/articles/devops). +DevOps methodology revolutionizes how development and operations teams work together to deliver software quickly and reliably. This article delves into the key principles and evolving roles within DevOps, helping organizations enhance productivity and collaboration. For a deeper dive into DevOps practices and resources, be sure to check out the extensive materials available on [GitHub's DevOps resources](https://github.com/resources/articles?topic=devops). ## What is DevOps? @@ -135,6 +135,6 @@ By closing the development-operations gap and fostering better collaboration, or -- [GitHub's DevOps Resources](https://github.com/resources/articles/devops) +- [GitHub's DevOps resources](https://github.com/resources/articles?topic=devops) - [What is DevOps? A guide to common methods and misconceptions](https://github.blog/enterprise-software/devops/devops-definition/) - [The evolving role of operations in DevOps](https://github.blog/enterprise-software/devops/the-evolving-role-of-operations-in-devops/) diff --git a/content/library/collaboration/recommendations/scaling-actions-reusability.md b/content/library/collaboration/recommendations/scaling-actions-reusability.md index c1e1da5..2d73ca6 100644 --- a/content/library/collaboration/recommendations/scaling-actions-reusability.md +++ b/content/library/collaboration/recommendations/scaling-actions-reusability.md @@ -191,7 +191,7 @@ Establishing a dedicated GitHub organization for shared workflows and actions pr - Set up branch rulesets to enforce code review and CI checks {{< callout type="info" >}} - GitHub branch rulesets provide more flexible and powerful options for protecting branches than the legacy branch protection rules. For detailed implementation instructions, refer to the [GitHub documentation on branch rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). + GitHub branch rulesets provide more flexible and powerful options for protecting branches than the legacy branch protection rules. For detailed implementation instructions, refer to the [GitHub documentation on branch rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). {{< /callout >}} Key ruleset configurations to consider: - Require status checks to pass before merging @@ -225,7 +225,7 @@ Establishing a dedicated GitHub organization for shared workflows and actions pr ``` {{< callout type="info" >}} - For a complete reference on Dependabot configuration options, including advanced settings like version constraints, commit message formatting, and custom labels, refer to the [GitHub Dependabot configuration documentation](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/working-with-dependabot/dependabot-options-reference). + For a complete reference on Dependabot configuration options, including advanced settings like version constraints, commit message formatting, and custom labels, refer to the [GitHub Dependabot configuration documentation](https://docs.github.com/enterprise-cloud@latest/code-security/reference/supply-chain-security/dependabot-options-reference). {{< /callout >}} 1. **Discoverability Features** @@ -235,7 +235,7 @@ Establishing a dedicated GitHub organization for shared workflows and actions pr - Configure custom repository properties to enhance filtering and discovery {{< callout type="info" >}} - Custom repository properties allow you to define organization-specific metadata that can be used for filtering repositories in the repository search interface. For detailed implementation instructions, refer to the [GitHub documentation on custom properties](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). + Custom repository properties allow you to define organization-specific metadata that can be used for filtering repositories in the repository search interface. For detailed implementation instructions, refer to the [GitHub documentation on custom properties](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). {{< /callout >}} Example custom properties to consider: @@ -578,7 +578,6 @@ priate mitigation strategies, you can maximize the benefits of centralized workf ### Additional Resources -- [GitHub Actions: Reusing workflows](https://docs.github.com/en/enterprise-cloud@latest/actions/sharing-automations/reusing-workflows) - Official documentation on workflow reusability -- [Creating composite actions](https://docs.github.com/en/enterprise-cloud@latest/actions/creating-actions/creating-a-composite-action) - Guide on building composite actions -- [Innersource principles for shared workflows](https://resources.github.com/innersource/fundamentals/) - GitHub's guide to innersource practices -- [Security best practices for GitHub Actions](https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) - Essential security considerations +- [GitHub Actions: Reusing workflows](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/reuse-automations/reuse-workflows) - Official documentation on workflow reusability +- [Creating a composite action](https://docs.github.com/enterprise-cloud@latest/actions/tutorials/create-actions/create-a-composite-action) - Guide on building composite actions +- [Secure use reference for GitHub Actions](https://docs.github.com/enterprise-cloud@latest/actions/reference/security/secure-use) - Essential security considerations diff --git a/content/library/governance/quick-links.md b/content/library/governance/quick-links.md index 9307600..57f0bd2 100644 --- a/content/library/governance/quick-links.md +++ b/content/library/governance/quick-links.md @@ -12,23 +12,23 @@ A curated list of resources and tools to enhance governance across the **Governa ## Control - [GitHub Security](https://github.com/security) -- [Available rules for rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) +- [Available rules for rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) - [GitHub Ruleset Recipes](https://github.com/github/ruleset-recipes) - [Get compliance data of Azure resources](https://learn.microsoft.com/en-us/azure/governance/policy/how-to/get-compliance-data) ## Auditability -- [Reviewing the audit log for your organization](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) -- [Reviewing your security log](https://docs.github.com/en/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log) -- [Viewing security insights](https://docs.github.com/en/enterprise-cloud@latest/code-security/security-overview/viewing-security-insights) +- [Reviewing the audit log for your organization](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) +- [Reviewing your security log](https://docs.github.com/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log) +- [Viewing security insights](https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/view-and-interpret-data/analyze-organization-data/viewing-security-insights) ## Accountability -- [About code owners](https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) -- [Managing teams and people with access to your repository](https://docs.github.com/en/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository) +- [About code owners](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) +- [Managing teams and people with access to your repository](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository) ## Adaptability -- [Understanding GitHub Actions](https://docs.github.com/en/enterprise-cloud@latest/actions/about-github-actions/understanding-github-actions) +- [Understanding GitHub Actions](https://docs.github.com/enterprise-cloud@latest/actions/get-started/understand-github-actions) - [GitHub Marketplace Integrations](https://github.com/marketplace) - [What is Azure Policy?](https://learn.microsoft.com/en-us/azure/governance/policy/overview) diff --git a/content/library/governance/recommendations/agentic-engineering-system-on-github.md b/content/library/governance/recommendations/agentic-engineering-system-on-github.md index a446abc..dc668d2 100644 --- a/content/library/governance/recommendations/agentic-engineering-system-on-github.md +++ b/content/library/governance/recommendations/agentic-engineering-system-on-github.md @@ -63,8 +63,8 @@ The table below maps each stock to the GitHub capabilities that build, store, or | Stock | GitHub capabilities | |---|---| -| **Governance (rule layer)** | [Repository rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets), [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), required status checks, [environment protection rules](https://docs.github.com/en/enterprise-cloud@latest/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments), [secret scanning with push protection](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning), [Dependabot](https://docs.github.com/en/code-security/dependabot), [code scanning](https://docs.github.com/en/code-security/code-scanning), [Copilot code review](https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review), [Copilot Code Quality](https://docs.github.com/en/copilot/how-tos/agents/copilot-code-review/configuring-coding-guidelines), [security configurations](https://docs.github.com/en/code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/about-custom-security-configurations), [audit log and audit log streaming](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization), Copilot Business or Enterprise admin policies, [MCP access policy](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/administer/enterprises/manage-github-copilot-in-your-enterprise/manage-mcp-servers-for-your-enterprise), agentic workflows, [agentic audit log fields](agentic-governance-taxonomy#agentic-audit-logs) (`actor_is_agent`, `agent_session_id`) | -| **Shared knowledge (information layer)** | Repository contents, [`.github/copilot-instructions.md`](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot), `.github/instructions/` path-scoped guidance, [issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository), pull request templates, architecture decision records committed to the repository, [GitHub Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis), [Discussions](https://docs.github.com/en/discussions), [Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects), linked issues and cross-references, [MCP servers](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-coding-agent-with-mcp) for external context | +| **Governance (rule layer)** | [Repository rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets), [CODEOWNERS](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners), required status checks, [environment protection rules](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments), [secret scanning with push protection](https://docs.github.com/code-security/concepts/secret-security/secret-scanning), [Dependabot](https://docs.github.com/code-security/concepts/supply-chain-security/dependabot-alerts), [code scanning](https://docs.github.com/code-security/concepts/code-scanning/code-scanning), [Copilot code review](https://docs.github.com/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review), [repository custom instructions](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), [security configurations](https://docs.github.com/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/create-custom-configuration), [audit log and audit log streaming](https://docs.github.com/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization), Copilot Business or Enterprise admin policies, [MCP access policy](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-mcp-usage), agentic workflows, [agentic audit log fields](agentic-governance-taxonomy#agentic-audit-logs) (`actor_is_agent`, `agent_session_id`) | +| **Shared knowledge (information layer)** | Repository contents, [`.github/copilot-instructions.md`](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions), `.github/instructions/` path-scoped guidance, [issue templates](https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository), pull request templates, architecture decision records committed to the repository, [GitHub Wiki](https://docs.github.com/communities/documenting-your-project-with-wikis), [Discussions](https://docs.github.com/discussions), [Projects](https://docs.github.com/issues/planning-and-tracking-with-projects), linked issues and cross-references, [MCP servers](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) for external context | ## Activities: GitHub primitives @@ -72,9 +72,9 @@ The table below maps each activity to the capabilities that support it. Many pri | Activity | GitHub capabilities | |---|---| -| **Define** | [Issues](https://docs.github.com/en/issues) with structured templates, [Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects) for prioritization and sprint planning, [labels](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work) and milestones, agent-drafted issues from custom Copilot agents, [Discussions](https://docs.github.com/en/discussions) for proposal-stage conversation | -| **Deliver** | [GitHub Copilot coding agent](https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks) (agent Performer), [GitHub Actions](https://docs.github.com/en/actions) (CI/CD orchestration), [pull requests](https://docs.github.com/en/pull-requests) (review and merge flow), [Codespaces](https://docs.github.com/en/codespaces) (development environments), [Packages](https://docs.github.com/en/packages), branch deploy workflows, [reusable workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows) for shared delivery patterns | -| **Detect** | [Actions](https://docs.github.com/en/actions) workflows that emit structured signal, [Dependabot alerts](https://docs.github.com/en/code-security/dependabot), [code scanning](https://docs.github.com/en/code-security/code-scanning) findings, [security advisories](https://docs.github.com/en/code-security/security-advisories), repository insights, deployment status checks, [webhooks](https://docs.github.com/en/webhooks) for external observability, [MCP servers](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-coding-agent-with-mcp) for telemetry ingestion, [Copilot usage metrics dashboard and API](https://github.blog/changelog/2025-10-28-copilot-usage-metrics-dashboard-and-api-in-public-preview/) | +| **Define** | [Issues](https://docs.github.com/issues) with structured templates, [Projects](https://docs.github.com/issues/planning-and-tracking-with-projects) for prioritization and sprint planning, [labels](https://docs.github.com/issues/using-labels-and-milestones-to-track-work) and milestones, agent-drafted issues from custom Copilot agents, [Discussions](https://docs.github.com/discussions) for proposal-stage conversation | +| **Deliver** | [Copilot cloud agent](https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent) (agent Performer), [GitHub Actions](https://docs.github.com/actions) (CI/CD orchestration), [pull requests](https://docs.github.com/pull-requests) (review and merge flow), [Codespaces](https://docs.github.com/codespaces) (development environments), [Packages](https://docs.github.com/packages), branch deploy workflows, [reusable workflows](https://docs.github.com/actions/how-tos/reuse-automations/reuse-workflows) for shared delivery patterns | +| **Detect** | [Actions](https://docs.github.com/actions) workflows that emit structured signal, [Dependabot alerts](https://docs.github.com/code-security/concepts/supply-chain-security/dependabot-alerts), [code scanning](https://docs.github.com/code-security/concepts/code-scanning/code-scanning) findings, [security advisories](https://docs.github.com/code-security/concepts/vulnerability-reporting-and-management/github-advisory-database), repository insights, deployment status checks, [webhooks](https://docs.github.com/webhooks) for external observability, [MCP servers](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) for telemetry ingestion, [Copilot usage metrics dashboard and API](https://github.blog/changelog/2025-10-28-copilot-usage-metrics-dashboard-and-api-in-public-preview/) | ## Common patterns @@ -84,7 +84,7 @@ A handful of patterns recur across teams that get agentic engineering working at **Instruction files as a primary work product.** `.github/copilot-instructions.md` and path-scoped instructions under `.github/instructions/` are kept current alongside code. Architectural conventions, file-layout expectations that cannot be inferred from directory names, and known pitfalls live in versioned files agents can read, not in tribal knowledge. In our experience, when agent-opened pull requests stop being merge-ready, the most effective intervention is rarely a better model: better shared knowledge, effective issue scoping, and accessible prior decisions tend to move the merge rate further than a model upgrade does. -**Structured handoffs from one cycle to the next.** Pull request descriptions describe intended behavior, what changed and why, what risks remain, what telemetry should be watched, and what the recovery path is if reality disagrees with the plan. Test outcomes, coverage, and static-analysis findings live in [checks](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow), pull request comments, and [coverage reports](https://docs.github.com/en/code-security/how-tos/maintain-quality-code/set-up-code-coverage) rather than being restated in the description. Issues link forward to the resulting pull requests and backward to the decisions that motivated them. Detect outputs are routed to the surface that best consumes them: incident reports, telemetry summaries, and customer feedback live in Issues, Discussions, or external systems accessible through MCP; corrections to how an agent handled a class of task route into instruction files where they can prevent the next occurrence. +**Structured handoffs from one cycle to the next.** Pull request descriptions describe intended behavior, what changed and why, what risks remain, what telemetry should be watched, and what the recovery path is if reality disagrees with the plan. Test outcomes, coverage, and static-analysis findings live in [checks](https://docs.github.com/pull-requests/reference/status-checks), pull request comments, and [coverage reports](https://docs.github.com/code-security/how-tos/maintain-quality-code/set-up-code-coverage) rather than being restated in the description. Issues link forward to the resulting pull requests and backward to the decisions that motivated them. Detect outputs are routed to the surface that best consumes them: incident reports, telemetry summaries, and customer feedback live in Issues, Discussions, or external systems accessible through MCP; corrections to how an agent handled a class of task route into instruction files where they can prevent the next occurrence. **Orchestrator and worker agents within pre-authorized scope.** When a task is too large or too diverse for a single agent execution, an orchestrator agent decomposes it and delegates sub-tasks to worker agents. The orchestrator holds Director mode toward the workers while remaining a Performer relative to the human Director above it. Industry writing sometimes calls this pattern [loop engineering](https://newsletter.pragmaticengineer.com/p/what-is-loop-engineering); the terminology is unsettled, but the shape is the same. This is a configuration of existing modes, not a new mode, and it is bounded by the same authorization rules as any other agent action. diff --git a/content/library/governance/recommendations/agentic-governance-taxonomy.md b/content/library/governance/recommendations/agentic-governance-taxonomy.md index 7e88a75..e5a3e85 100644 --- a/content/library/governance/recommendations/agentic-governance-taxonomy.md +++ b/content/library/governance/recommendations/agentic-governance-taxonomy.md @@ -43,15 +43,15 @@ A note on scope: telemetry, incident records, decisions, runbooks, and customer ### Sub-categories of agent governance -**1. Identity and access context.** Who and what is recognized by the system, and at what scope. This is the foundational sub-category: every other control assumes a trustworthy answer to "who is acting." It covers human identity (SAML or OIDC single sign-on, [SCIM provisioning](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management), organization and team membership, [repository roles](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization), IP allow lists), machine identity ([GitHub Apps](https://docs.github.com/en/apps) and their installation permissions, [fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [OIDC trust between GitHub Actions and remote systems](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)), and agent identity (Copilot seat assignment, and the identity an agent acts under when it opens a pull request, runs a workflow, or calls a tool through MCP). It is a prerequisite for every other category and most visible when an agent attempts to act, since identity determines what the action is permitted to be. +**1. Identity and access context.** Who and what is recognized by the system, and at what scope. This is the foundational sub-category: every other control assumes a trustworthy answer to "who is acting." It covers human identity (SAML or OIDC single sign-on, [SCIM provisioning](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim), organization and team membership, [repository roles](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization), IP allow lists), machine identity ([GitHub Apps](https://docs.github.com/apps) and their installation permissions, [fine-grained personal access tokens](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [OIDC trust between GitHub Actions and remote systems](https://docs.github.com/actions/concepts/security/openid-connect)), and agent identity (Copilot seat assignment, and the identity an agent acts under when it opens a pull request, runs a workflow, or calls a tool through MCP). It is a prerequisite for every other category and most visible when an agent attempts to act, since identity determines what the action is permitted to be. -**2. Authorization and action boundaries.** What an authenticated identity is permitted to do on protected resources. This is the largest surface and the one most often confused with governance as a whole. It includes [repository rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets) (required pull requests, required reviewers, required status checks, restrictions on force-push and deletion, signed commit requirements, linear history), [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for review routing, [environment protection rules](https://docs.github.com/en/enterprise-cloud@latest/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments) (required reviewers, wait timers, branch and tag restrictions, deployment branch policies), [GitHub Actions permissions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication) (default `GITHUB_TOKEN` scope, allowed actions list, fork pull request workflow approval, actions policies), and Copilot configuration and policies that govern which models, content, and tools agents may use. The boundary between "agent acts autonomously" and "human approval required" is encoded almost entirely in this sub-category. +**2. Authorization and action boundaries.** What an authenticated identity is permitted to do on protected resources. This is the largest surface and the one most often confused with governance as a whole. It includes [repository rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets) (required pull requests, required reviewers, required status checks, restrictions on force-push and deletion, signed commit requirements, linear history), [CODEOWNERS](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for review routing, [environment protection rules](https://docs.github.com/enterprise-cloud@latest/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments) (required reviewers, wait timers, branch and tag restrictions, deployment branch policies), [GitHub Actions permissions](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) (default `GITHUB_TOKEN` scope, allowed actions list, fork pull request workflow approval, actions policies), and Copilot configuration and policies that govern which models, content, and tools agents may use. The boundary between "agent acts autonomously" and "human approval required" is encoded almost entirely in this sub-category. -**3. Automated assurance controls.** The deterministic checks evaluated against work in flight, configured as required gates rather than advisory output. These controls establish a quality floor for every change and, in aggregate, define the risk envelope the system will tolerate. On the same repository they may be experienced two ways: for well-bounded work the floor plus targeted automation carries most of the load without heavy human attention; for high-stakes work the floor is a prerequisite, not a substitute, for deeper review. Weak floor guardrails let agents (and humans) generate lower-quality work faster; strong ones raise the baseline of everything that ships. They include [code scanning](https://docs.github.com/en/code-security/code-scanning) (CodeQL and third-party tools), [secret scanning with push protection](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning), [Dependabot alerts and security updates](https://docs.github.com/en/code-security/dependabot), the [dependency review action](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review), [artifact attestations and build provenance](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations-to-establish-provenance-for-builds), required status checks tied to CI suites, and [security configurations](https://docs.github.com/en/code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/about-custom-security-configurations) that apply enforcement choices consistently across many repositories. The same scanner is governance when it blocks a merge and is detection when its findings are routed for triage; the configuration that makes it blocking belongs here, the finding it produces becomes context. +**3. Automated assurance controls.** The deterministic checks evaluated against work in flight, configured as required gates rather than advisory output. These controls establish a quality floor for every change and, in aggregate, define the risk envelope the system will tolerate. On the same repository they may be experienced two ways: for well-bounded work the floor plus targeted automation carries most of the load without heavy human attention; for high-stakes work the floor is a prerequisite, not a substitute, for deeper review. Weak floor guardrails let agents (and humans) generate lower-quality work faster; strong ones raise the baseline of everything that ships. They include [code scanning](https://docs.github.com/code-security/concepts/code-scanning/code-scanning) (CodeQL and third-party tools), [secret scanning with push protection](https://docs.github.com/code-security/concepts/secret-security/secret-scanning), [Dependabot alerts and security updates](https://docs.github.com/code-security/concepts/supply-chain-security/dependabot-alerts), the [dependency review action](https://docs.github.com/code-security/concepts/supply-chain-security/dependency-review), [artifact attestations and build provenance](https://docs.github.com/actions/concepts/security/artifact-attestations), required status checks tied to CI suites, and [security configurations](https://docs.github.com/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/create-custom-configuration) that apply enforcement choices consistently across many repositories. The same scanner is governance when it blocks a merge and is detection when its findings are routed for triage; the configuration that makes it blocking belongs here, the finding it produces becomes context. -**4. Audit, provenance, and evidence.** The system's governance memory: the record of who did what, when, under which rule, and with which result. This is what makes governance verifiable rather than aspirational, and it is what auditors, security reviewers, and incident responders rely on. It includes the [enterprise audit log](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise) and [audit log streaming](https://docs.github.com/en/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise), [signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) and tag signature verification, artifact attestations, deployment history per environment, the [security overview](https://docs.github.com/en/code-security/security-overview/about-security-overview), repository security advisories, and the [agentic audit log fields](#agentic-audit-logs) described below. This category feeds the Define activity in any improvement cycle: when the record reveals a missing rule or a recurring exception, that exception becomes the next rule. +**4. Audit, provenance, and evidence.** The system's governance memory: the record of who did what, when, under which rule, and with which result. This is what makes governance verifiable rather than aspirational, and it is what auditors, security reviewers, and incident responders rely on. It includes the [enterprise audit log](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise) and [audit log streaming](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise), [signed commits](https://docs.github.com/authentication/managing-commit-signature-verification/about-commit-signature-verification) and tag signature verification, artifact attestations, deployment history per environment, the [security overview](https://docs.github.com/code-security/concepts/security-at-scale/security-overview), repository security advisories, and the [agentic audit log fields](#agentic-audit-logs) described below. This category feeds the Define activity in any improvement cycle: when the record reveals a missing rule or a recurring exception, that exception becomes the next rule. -**5. Policy definition and distribution.** The codified rules upstream of enforcement: how policy is expressed, owned, versioned, and propagated to the repositories and environments it applies to. Without this layer, the controls in the other four sub-categories drift per repository and the stack stops being a stack. It includes organization and enterprise policies (base permissions, repository creation, visibility, OAuth app and GitHub App approval, Actions policies and allowlists), [repository rulesets defined at organization or enterprise scope](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization), [custom repository properties](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) and [organization custom properties](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-custom-properties-for-organizations) used as targeting metadata for rulesets and policy (including [Copilot cloud agent enablement](https://github.blog/changelog/2026-04-15-enable-copilot-cloud-agent-via-custom-properties/)), [security configurations](https://docs.github.com/en/code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/about-custom-security-configurations) as reusable bundles, required workflows, and Copilot Business or Enterprise admin policies (content exclusions, model availability, public code matching). This is the layer that turns governance into a system rather than a set of repository-local choices. +**5. Policy definition and distribution.** The codified rules upstream of enforcement: how policy is expressed, owned, versioned, and propagated to the repositories and environments it applies to. Without this layer, the controls in the other four sub-categories drift per repository and the stack stops being a stack. It includes organization and enterprise policies (base permissions, repository creation, visibility, OAuth app and GitHub App approval, Actions policies and allowlists), [repository rulesets defined at organization or enterprise scope](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization), [custom repository properties](https://docs.github.com/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) and [organization custom properties](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-custom-properties-for-organizations) used as targeting metadata for rulesets and policy (including [Copilot cloud agent enablement](https://github.blog/changelog/2026-04-15-enable-copilot-cloud-agent-via-custom-properties/)), [security configurations](https://docs.github.com/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/create-custom-configuration) as reusable bundles, required workflows, and Copilot Business or Enterprise admin policies (content exclusions, model availability, public code matching). This is the layer that turns governance into a system rather than a set of repository-local choices. ### Agentic audit logs diff --git a/content/library/governance/recommendations/agentic-shared-knowledge.md b/content/library/governance/recommendations/agentic-shared-knowledge.md index f5bc0fd..149dd61 100644 --- a/content/library/governance/recommendations/agentic-shared-knowledge.md +++ b/content/library/governance/recommendations/agentic-shared-knowledge.md @@ -33,7 +33,7 @@ features: - copilot --- -The quality of every action an agent takes is bounded by the quality of the context available to it. A coding agent generating a payment retry flow cannot consider an architectural constraint it has never read, cannot follow a convention it has never been shown, and cannot avoid a known pitfall recorded only in someone's head. As Anthropic's engineering team [put it in 2025](https://www.anthropic.com/engineering/effective-context-engineering-for-aiagents), "context is a critical but finite resource for AI agents." This guide describes shared knowledge as the context the engineering system holds, and provides a taxonomy for inventorying and improving it. +The quality of every action an agent takes is bounded by the quality of the context available to it. A coding agent generating a payment retry flow cannot consider an architectural constraint it has never read, cannot follow a convention it has never been shown, and cannot avoid a known pitfall recorded only in someone's head. As Anthropic's engineering team [put it in 2025](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), "context is a critical but finite resource for AI agents." This guide describes shared knowledge as the context the engineering system holds, and provides a taxonomy for inventorying and improving it. ## Why shared knowledge matters @@ -49,19 +49,19 @@ Five sub-categories together cover the context the engineering system holds. The ### 1. Code context -The current state of the codebase: production code, tests, infrastructure-as-code, build configuration, dependency graphs, and the technical debt embedded in them, plus the artifacts that shape how agents work within that code. This is what an agent or human reads before changing anything. Well-named code and thorough unit tests are often the most effective information an agent has, since they demonstrate correct behavior more reliably than standalone documentation and they surface in retrieval where prose descriptions may not. On GitHub, code context lives primarily in repositories themselves, supplemented by [`.github/copilot-instructions.md`](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) for repository-level conventions, `.github/instructions/` for path-scoped guidance, [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for ownership signals, and skill and agent definitions (`AGENTS.md`, `SKILL.md`, custom agent configurations) that shape long-term agent behavior alongside the code they act on. +The current state of the codebase: production code, tests, infrastructure-as-code, build configuration, dependency graphs, and the technical debt embedded in them, plus the artifacts that shape how agents work within that code. This is what an agent or human reads before changing anything. Well-named code and thorough unit tests are often the most effective information an agent has, since they demonstrate correct behavior more reliably than standalone documentation and they surface in retrieval where prose descriptions may not. On GitHub, code context lives primarily in repositories themselves, supplemented by [`.github/copilot-instructions.md`](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) for repository-level conventions, `.github/instructions/` for path-scoped guidance, [CODEOWNERS](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for ownership signals, and skill and agent definitions (`AGENTS.md`, `SKILL.md`, custom agent configurations) that shape long-term agent behavior alongside the code they act on. Primary activity served: `Deliver`, with strong feedback into `Define` when code reveals a constraint that should shape the next decision. ### 2. Intent, decision, and knowledge context -The record of why the system is the way it is, together with the broader internal corpus that explains how it works: product requirements, architecture decision records, design docs, roadmaps, RFCs, resolved-issue history, runbooks, onboarding docs, internal wikis, glossaries, team handbooks, and the corpora that get indexed into retrieval systems. On GitHub, this material lives in [Issues](https://docs.github.com/en/issues), [Discussions](https://docs.github.com/en/discussions), [Wikis](https://docs.github.com/en/communities/documenting-your-project-with-wikis), repository documentation under `docs/`, and increasingly through [MCP servers](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-coding-agent-with-mcp) that surface external knowledge bases. +The record of why the system is the way it is, together with the broader internal corpus that explains how it works: product requirements, architecture decision records, design docs, roadmaps, RFCs, resolved-issue history, runbooks, onboarding docs, internal wikis, glossaries, team handbooks, and the corpora that get indexed into retrieval systems. On GitHub, this material lives in [Issues](https://docs.github.com/issues), [Discussions](https://docs.github.com/discussions), [Wikis](https://docs.github.com/communities/documenting-your-project-with-wikis), repository documentation under `docs/`, and increasingly through [MCP servers](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) that surface external knowledge bases. Primary activity served: `Define`, with relevance to all activities depending on the query. ### 3. Operational signal context -Live and historical signals from the running system: telemetry, logs, traces, metrics, incident records, evaluation results, and agent reasoning traces. The [Copilot usage metrics dashboard and API](https://github.blog/changelog/2025-10-28-copilot-usage-metrics-dashboard-and-api-in-public-preview/), Actions run history, [Dependabot alerts](https://docs.github.com/en/code-security/dependabot), [code scanning](https://docs.github.com/en/code-security/code-scanning) findings, [Copilot Code Quality](https://docs.github.com/en/copilot/how-tos/agents/copilot-code-review/configuring-coding-guidelines) outputs, deployment history, and external observability platforms surfaced through MCP all contribute to this category. Evaluations and benchmarks sit inside this sub-category rather than as a separate one, on the basis that they are operational measurements of system behavior. +Live and historical signals from the running system: telemetry, logs, traces, metrics, incident records, evaluation results, and agent reasoning traces. The [Copilot usage metrics dashboard and API](https://github.blog/changelog/2025-10-28-copilot-usage-metrics-dashboard-and-api-in-public-preview/), Actions run history, [Dependabot alerts](https://docs.github.com/code-security/concepts/supply-chain-security/dependabot-alerts), [code scanning](https://docs.github.com/code-security/concepts/code-scanning/code-scanning) findings, [GitHub Code Quality](https://docs.github.com/code-security/concepts/code-quality/code-quality) outputs, deployment history, and external observability platforms surfaced through MCP all contribute to this category. Evaluations and benchmarks sit inside this sub-category rather than as a separate one, on the basis that they are operational measurements of system behavior. Primary activity served: feeds Define (it comes from Detect). @@ -73,7 +73,7 @@ Primary activity served: Define, with feedback into Detect when a customer signa ### 5. Agent memory and session context -The state agents accumulate within and across runs: scratchpads, episodic memory, learned task patterns, prior tool-call results, and inter-agent handoff artifacts. Most of this material has a short effective half-life. Reasoning traces and tool-call histories often stop being relevant the moment the underlying code changes, and old traces re-entered into a fresh context can push an agent toward outdated behaviors. Two subsets have longer value. First, patterns that generalize, such as recurring conventions or effective task decompositions, are worth graduating into skills or instruction files rather than left buried in session logs. Second, the trace itself is the primary evidence base for auditing what an agent did and for improving the shared knowledge that guided it: [agent session streaming](https://github.blog/changelog/2026-07-02-copilot-agent-session-streaming-is-now-in-public-preview/) (public preview) is the emerging mechanism for turning that evidence base into a durable signal that can be joined against other metrics. On GitHub today, much of this material is implicit in the conversation history of an [agent session](https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks) or the artifacts an agent leaves behind in pull request descriptions, comments, and commit messages. Treating the durable subset as structured outputs, and letting the ephemeral remainder age out, is what turns this sub-category from a liability into shared knowledge. +The state agents accumulate within and across runs: scratchpads, episodic memory, learned task patterns, prior tool-call results, and inter-agent handoff artifacts. Most of this material has a short effective half-life. Reasoning traces and tool-call histories often stop being relevant the moment the underlying code changes, and old traces re-entered into a fresh context can push an agent toward outdated behaviors. Two subsets have longer value. First, patterns that generalize, such as recurring conventions or effective task decompositions, are worth graduating into skills or instruction files rather than left buried in session logs. Second, the trace itself is the primary evidence base for auditing what an agent did and for improving the shared knowledge that guided it: [agent session streaming](https://github.blog/changelog/2026-07-02-copilot-agent-session-streaming-is-now-in-public-preview/) (public preview) is the emerging mechanism for turning that evidence base into a durable signal that can be joined against other metrics. On GitHub today, much of this material is implicit in the conversation history of an [agent session](https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions) or the artifacts an agent leaves behind in pull request descriptions, comments, and commit messages. Treating the durable subset as structured outputs, and letting the ephemeral remainder age out, is what turns this sub-category from a liability into shared knowledge. Primary activity served: `Deliver` primarily, but relevant whenever an agent runs. diff --git a/content/library/governance/recommendations/governance-administration-essentials.md b/content/library/governance/recommendations/governance-administration-essentials.md index 4c8c905..b5dda8c 100644 --- a/content/library/governance/recommendations/governance-administration-essentials.md +++ b/content/library/governance/recommendations/governance-administration-essentials.md @@ -85,7 +85,7 @@ GHEC provides a number of flexible configuration options, allowing each business ### Enterprise account -The [enterprise account](https://docs.github.com/enterprise-cloud@latest/admin/overview/about-enterprise-accounts) is the highest-level construct within GHEC. Treat it as an administrative-only control plane for billing, licensing, identity provider integration, support entitlements, log management, and enterprise-wide policy enforcement. Standard end users do not typically have any need to interact with the enterprise account interface. +The [enterprise account](https://docs.github.com/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/enterprise-accounts) is the highest-level construct within GHEC. Treat it as an administrative-only control plane for billing, licensing, identity provider integration, support entitlements, log management, and enterprise-wide policy enforcement. Standard end users do not typically have any need to interact with the enterprise account interface. ### Organizations @@ -111,7 +111,7 @@ Permissions aren't the only use for teams, though. You can use GitHub teams to e In terms of hierarchy and configuration inheritance, teams roll up to the organization level. This means that in order to reuse the same team across many organizations within your enterprise account, you would need to recreate it in each organization. -Enterprise owners can view and manage teams across all organizations from the enterprise level. For EMU enterprises, this extends further: team membership can be [synchronized with IdP groups at the enterprise level](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups), rather than configuring group sync independently in each organization. This is a significant operational advantage in multi-organization deployments where the same platform, security, or compliance teams need consistent access across all organizations. A single IdP group mapping governs membership in all of them. +Enterprise owners can view and manage teams across all organizations from the enterprise level. For EMU enterprises, this extends further: team membership can be [synchronized with IdP groups at the enterprise level](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups), rather than configuring group sync independently in each organization. This is a significant operational advantage in multi-organization deployments where the same platform, security, or compliance teams need consistent access across all organizations. A single IdP group mapping governs membership in all of them. [Enterprise teams](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/create-enterprise-teams) take this further by allowing you to define teams at the enterprise level and grant them administrative roles or add them directly to organizations. If you need the same team to operate across multiple organizations, evaluate enterprise teams as a way to reduce duplicated team configurations and simplify cross-organization access management. @@ -145,7 +145,7 @@ The standard model also permits both private and public repositories to be hoste The EMU model prioritizes centralized enterprise control of a standardized work account from a corporate IdP. The EMU model uses company-owned, work-only GitHub accounts that operate exclusively within the confines of a company's enterprise account. When a user joins your company and is given GHEC access, they get an EMU work account that only operates and is visible in your company's enterprise account. When they leave your company or otherwise lose their GHEC access, that EMU work account is also suspended. -The full lifecycle of these accounts, including authentication and provisioning, is managed by a supported IdP, such as Microsoft Entra ID (formerly Azure Active Directory), Okta, or PingFederate. EMU supports both SAML and [OIDC](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users) for authentication. OIDC is the recommended choice when using Microsoft Entra ID, as it enables Entra ID's [Conditional Access Policy](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy) (CAP) to govern GitHub access alongside other corporate resources. This provides a unified access control posture and removes the need for a separate IP allow list. +The full lifecycle of these accounts, including authentication and provisioning, is managed by a supported IdP, such as Microsoft Entra ID (formerly Azure Active Directory), Okta, or PingFederate. EMU supports both SAML and [OIDC](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users) for authentication. OIDC is the recommended choice when using Microsoft Entra ID, as it enables Entra ID's [Conditional Access Policy](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy) (CAP) to govern GitHub access alongside other corporate resources. This provides a unified access control posture and removes the need for a separate IP allow list. The enterprise can standardize EMU account information, including username formatting, email addresses, and display names, which supports improved transparency and reporting. @@ -203,7 +203,7 @@ The following three models represent the most common organization architecture p A single organization serves all or the vast majority of repositories. This model works well when your collaboration, compliance, and access needs can be managed within a single administrative boundary using teams and repository permissions. -Most users of this model set their organization's [base permissions](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization) to none, requiring explicit team assignment for repository access. By itself, this approach creates silos, greatly limits visibility, and actively prevents innersource. To counter this tendency, we recommend creating an "all members" team and adding it to repositories that should be open for collaboration. You can even have this team automatically added to all repositories by default, with an exception process for truly need-to-know repositories. +Most users of this model set their organization's [base permissions](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization) to none, requiring explicit team assignment for repository access. By itself, this approach creates silos, greatly limits visibility, and actively prevents innersource. To counter this tendency, we recommend creating an "all members" team and adding it to repositories that should be open for collaboration. You can even have this team automatically added to all repositories by default, with an exception process for truly need-to-know repositories. Slight variations on this model exist to handle extenuating circumstances. For example, you might maintain one or two restricted organizations for projects that must be kept completely separate from all other work, like projects for highly sensitive customers. Similarly, you might use a separate organization to segment repositories managed by teams in particular locations to address concerns around intellectual property laws. @@ -246,7 +246,7 @@ Teams and member roles sit at the very bottom of GHEC's structural hierarchy and ### Inviting and assigning users to organizations -Users need to be given access to organizations in order to gain access to content. EMU enterprises assign users to organizations via IdP provisioning, while standard enterprises invite users, who must accept. The best way to manage user membership in your organizations is to add users to teams, because it allows you to use automation like [group SCIM](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups) (EMU) or [organization SCIM](https://docs.github.com/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations) (non-EMU) to manage organization membership. +Users need to be given access to organizations in order to gain access to content. EMU enterprises assign users to organizations via IdP provisioning, while standard enterprises invite users, who must accept. The best way to manage user membership in your organizations is to add users to teams, because it allows you to use automation like [group SCIM](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups) (EMU) or [organization SCIM](https://docs.github.com/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations) (non-EMU) to manage organization membership. Managing organizations through automation means you don't have to remember to remove users manually to ensure their access and license are removed if and when they leave an organization. @@ -280,15 +280,15 @@ EMU enterprises must provision all enterprise members and administrative roles t - **GitHub App manager**: Can manage settings of [GitHub App registrations](https://docs.github.com/enterprise-cloud@latest/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization) owned by an organization, but cannot install or uninstall apps. - **Team maintainer**: Can manage team membership and settings, like team name and avatar. Teams that use IdP groups to automate membership do not and cannot have maintainers by design, since there is a very limited scope of work for a maintainer to do when they cannot manually update user membership. -Organization owners can also create [custom organization roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles) with a specific combination of permissions. Custom roles let you elevate a user above the default Member permission set without granting full organization owner access. They are well-suited for personas with narrowly scoped administrative responsibilities, such as CI/CD administrators, audit log reviewers, or Dependabot managers. Custom organization roles apply least privilege at the organizational level in the same way custom repository roles do at the repository level. +Organization owners can also create [custom organization roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles) with a specific combination of permissions. Custom roles let you elevate a user above the default Member permission set without granting full organization owner access. They are well-suited for personas with narrowly scoped administrative responsibilities, such as CI/CD administrators, audit log reviewers, or Dependabot managers. Custom organization roles apply least privilege at the organizational level in the same way custom repository roles do at the repository level. ### Repository roles and custom roles -Do not use Admin as a default repository permission. Use Read or Write as a starting point and rely on rulesets to control how code reaches protected branches. For the full set of [repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) and their capabilities, see GitHub Docs. +Do not use Admin as a default repository permission. Use Read or Write as a starting point and rely on rulesets to control how code reaches protected branches. For the full set of [repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) and their capabilities, see GitHub Docs. When different levels of access are given through different routes, such as team membership and the base permissions for an organization, the highest access overrides for each specific permission. If a person has been given conflicting access, you'll see a "Mixed roles" warning on the repository access page. You do not necessarily need to resolve conflicting access. This information is there for your awareness so that the conflicting permissions do not cause confusion. -You can create up to five [custom repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles) per organization for more granular control. Custom repository roles inherit permissions from a default role and then add [additional permissions](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles#additional-permissions-for-custom-roles). After you create a custom role, anyone with admin access to a repository can assign the role to an individual or team. +You can create [custom repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles) for more granular control. Custom repository roles inherit permissions from a default role and then add [additional permissions](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles#additional-permissions-for-custom-roles). After you create a custom role, anyone with admin access to a repository can assign the role to an individual or team. ## Programmatic access and integrations @@ -308,9 +308,9 @@ If you want to centrally manage command line access and avoid per-user PAT manag ### IP allow lists -If you configure an [IP allow list](https://docs.github.com/enterprise-cloud@latest/admin/configuration/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list), include the IP ranges of all installed integrations. Missing ranges will cause integrations to silently fail. EMU enterprises using OIDC must also add integration IP ranges to their IdP's [conditional access policy](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy) (CAP). +If you configure an [IP allow list](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list), include the IP ranges of all installed integrations. Missing ranges will cause integrations to silently fail. EMU enterprises using OIDC must also add integration IP ranges to their IdP's [conditional access policy](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy) (CAP). -For GitHub-hosted Actions runners with [four or more vCPUs](https://docs.github.com/enterprise-cloud@latest/actions/using-github-hosted-runners/using-larger-runners#networking-for-larger-runners), you can receive a static IP address unique to your enterprise to add to your allow list or IdP CAP. +For GitHub-hosted Actions runners with [four or more vCPUs](https://docs.github.com/enterprise-cloud@latest/actions/concepts/runners/larger-runners#about-larger-runners), you can receive a static IP address unique to your enterprise to add to your allow list or IdP CAP. ### GitHub Apps @@ -334,9 +334,9 @@ Webhooks provide a way for notifications to be delivered to an external web serv **On-premises webhook delivery**: As part of your GHEC deployment, you may need webhooks to send notifications to applications hosted behind your firewall. With proper network configuration, GHEC can notify these systems by implementing a form of reverse proxy, which includes a publicly routable fully-qualified domain name (FQDN) and URL rewrite and port forwarding to the appropriate application. This pattern can be implemented using off-the-shelf components from vendors like ngrok, configuring existing web servers like NGINX, or a commercial product such as a WAF or API gateway. -**Securing webhook deliveries**: When implementing a reverse proxy to handle webhook delivery, only allow inbound HTTPS traffic on port 443, restrict traffic to GitHub's [webhook IP ranges](https://api.github.com/meta), terminate SSL and inspect payloads, and ensure integrations use [webhook signatures](https://docs.github.com/developers/webhooks-and-events/webhooks/securing-your-webhooks). +**Securing webhook deliveries**: When implementing a reverse proxy to handle webhook delivery, only allow inbound HTTPS traffic on port 443, restrict traffic to GitHub's [webhook IP ranges](https://docs.github.com/webhooks/using-webhooks/best-practices-for-using-webhooks#allow-githubs-ip-addresses), terminate SSL and inspect payloads, and ensure integrations use [webhook signatures](https://docs.github.com/webhooks/using-webhooks/validating-webhook-deliveries). -**Avoid API polling**: If you are writing an integration or automation against the GitHub API, you should avoid API polling. GitHub enforces [rate limits](https://docs.github.com/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limits-for-requests-from-personal-accounts) on API activity. Regularly polling the API, especially in larger organizations, will hit the rate limit. Rather than polling on a scheduled basis, you should use webhooks to be notified of events on GitHub instead. +**Avoid API polling**: If you are writing an integration or automation against the GitHub API, you should avoid API polling. GitHub enforces [rate limits](https://docs.github.com/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28) on API activity. Regularly polling the API, especially in larger organizations, will hit the rate limit. Rather than polling on a scheduled basis, you should use webhooks to be notified of events on GitHub instead. ## Audit log operations @@ -344,7 +344,7 @@ Whether you operate in a highly regulated industry or not, audit logs are an ess ### What audit logs include and why streaming matters -GHEC audit logs cover configuration changes, API access, and Git events at both the [enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise) and [organization](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#accessing-the-audit-log) levels. For the full list of audited event types and retention periods, see [About the audit log for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise). +GHEC audit logs cover configuration changes, API access, and Git events at both the [enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise) and [organization](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#accessing-the-audit-log) levels. For retention periods, see [Audit log for an enterprise](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/audit-log-for-an-enterprise). For the full list of audited event types, see [Audit log events for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). Default retention is limited, so set up audit log streaming from day one. If streaming is not feasible, automate periodic exports to retain data beyond the default retention window. @@ -410,17 +410,17 @@ GHEC uses a unique-user licensing model, which means that GitHub counts each mem ### Consumption-based services -Use of consumption-based services, such as GitHub-hosted Actions runners, shared storage for GitHub Actions and Packages, and Codespaces, are billed per unit consumed. Consumption across all of your enterprise's organizations will be aggregated to a single invoice at the enterprise level. Your GHEC plan includes a flat amount of storage and usage ([entitlements](https://docs.github.com/enterprise-cloud@latest/billing/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes)) per month. These included services are intended to help your company get started using GitHub Actions and Packages, such as by enabling simple workflow automations, supporting pilot activities, running tests of security scans, and other non-business-critical usage. If you intend to use GitHub Actions and/or Packages as part of your production DevSecOps pipelines, you should plan to set up payment and spending limits to ensure you can continue to use these services beyond the included entitlements each month. +Use of consumption-based services, such as GitHub-hosted Actions runners, shared storage for GitHub Actions and Packages, and Codespaces, are billed per unit consumed. Consumption across all of your enterprise's organizations will be aggregated to a single invoice at the enterprise level. Your GHEC plan includes a flat amount of storage and usage ([entitlements](https://docs.github.com/enterprise-cloud@latest/billing/concepts/product-billing/github-actions#free-use-of-github-actions)) per month. These included services are intended to help your company get started using GitHub Actions and Packages, such as by enabling simple workflow automations, supporting pilot activities, running tests of security scans, and other non-business-critical usage. If you intend to use GitHub Actions and/or Packages as part of your production DevSecOps pipelines, you should plan to set up payment and spending limits to ensure you can continue to use these services beyond the included entitlements each month. -**Payment**: You can [connect an Azure Subscription ID](https://docs.github.com/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription) to your enterprise account to pay for any consumption-based services overages beyond your enterprise's entitlements. This is the preferred billing method over monthly invoices. The Azure subscription will be used only for billing purposes; no resources will be created or used in your Azure subscription itself. To connect your Azure subscription, you must have owner permissions to the Azure subscription and be an enterprise owner on GitHub. +**Payment**: You can [connect an Azure Subscription ID](https://docs.github.com/enterprise-cloud@latest/billing/how-tos/set-up-payment/connect-azure-sub) to your enterprise account to pay for any consumption-based services overages beyond your enterprise's entitlements. This is the preferred billing method over monthly invoices. The Azure subscription will be used only for billing purposes; no resources will be created or used in your Azure subscription itself. To connect your Azure subscription, you must have owner permissions to the Azure subscription and be an enterprise owner on GitHub. -**Spending limits**: Set per-service spending limits for [Actions](https://docs.github.com/enterprise-cloud@latest/billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions), [Packages](https://docs.github.com/enterprise-cloud@latest/billing/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages), and [Codespaces](https://docs.github.com/enterprise-cloud@latest/billing/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). A $0 spending limit prevents any additional charges for that service, but still allows use of that service until the included entitlements are used up. You can also set your spending limit to unlimited, which will keep a service running regardless of how much is spent. The default spending limit for invoiced customers is set to unlimited, so if you would prefer to set a specific spending limit, be sure to update it. +**Spending limits**: [Set budgets](https://docs.github.com/enterprise-cloud@latest/billing/how-tos/set-up-budgets) to control spending on metered products such as Actions, Packages, and Codespaces. A $0 spending limit prevents any additional charges for that service, but still allows use of that service until the included entitlements are used up. You can also set your spending limit to unlimited, which will keep a service running regardless of how much is spent. The default spending limit for invoiced customers is set to unlimited, so if you would prefer to set a specific spending limit, be sure to update it. **Reporting**: Insight into consumption services billing is provided at both the per-organization and aggregate enterprise levels. You can view monthly consumption in the user interface, or you can download granular usage reports in a CSV format. These reports are intended to be a starting point for your further analysis, chargebacks, or other more in-depth reporting. ### Cost centers -For multi-organization enterprises, [cost centers](https://docs.github.com/enterprise-cloud@latest/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises) let you allocate consumption spending to specific business units independently from your organization structure. Define cost centers early, alongside your initial billing configuration, so that spending data is attributed correctly from the start. If your enterprise is billed through Azure, you can also map cost centers to separate Azure subscriptions, which simplifies chargeback reporting for finance teams. Without cost centers, consumption data is only broken down by organization, which may not align with how your business tracks budgets. +For multi-organization enterprises, [cost centers](https://docs.github.com/enterprise-cloud@latest/billing/concepts/cost-centers) let you allocate consumption spending to specific business units independently from your organization structure. Define cost centers early, alongside your initial billing configuration, so that spending data is attributed correctly from the start. If your enterprise is billed through Azure, you can also map cost centers to separate Azure subscriptions, which simplifies chargeback reporting for finance teams. Without cost centers, consumption data is only broken down by organization, which may not align with how your business tracks budgets. ## Repository governance and visibility @@ -456,7 +456,7 @@ Branch protection rules are a legacy method of mergeability control. Rulesets ar ### Repository settings -A few of the same settings seen at the enterprise and organization levels are available at the individual repository level, including [Actions policies](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository), [security feature enablement](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository), and [forking settings](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository). You can also enable and disable features like [Issues](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues), [GitHub Discussions](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository), and [Projects](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository) per repository, which can be useful when you need to limit the use of certain repositories, such as during feature rollouts or when archiving content. +A few of the same settings seen at the enterprise and organization levels are available at the individual repository level, including [Actions policies](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository), [security feature enablement](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository), and [forking settings](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository). You can also enable and disable features like [Issues](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues), [GitHub Discussions](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository), and [Projects](https://docs.github.com/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-projects-in-a-repository) per repository, which can be useful when you need to limit the use of certain repositories, such as during feature rollouts or when archiving content. For any repository-level settings, these must be set to be more restrictive than any enterprise or organization policies or settings. For example, if your enterprise or organization policy is set to disallow any forking, you will not be able to allow forking per repository. However, if the policy for your enterprise or organization permits use of any actions, you can set a per-repository policy to only permit use of a specified list of allowed actions in that repository. @@ -521,34 +521,34 @@ Custom properties are most powerful when paired with enterprise-level rulesets. ## Related links -- [Best practices for enterprises](https://docs.github.com/enterprise-cloud@latest/admin/overview/best-practices-for-enterprises) -- [About enterprise accounts](https://docs.github.com/enterprise-cloud@latest/admin/overview/about-enterprise-accounts) +- [Best practices for enterprises](https://docs.github.com/enterprise-cloud@latest/admin/concepts/enterprise-best-practices) +- [Enterprise accounts](https://docs.github.com/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/enterprise-accounts) - [About organizations](https://docs.github.com/enterprise-cloud@latest/organizations/collaborating-with-groups-in-organizations/about-organizations) - [About teams](https://docs.github.com/enterprise-cloud@latest/organizations/organizing-members-into-teams/about-teams) - [About repositories](https://docs.github.com/enterprise-cloud@latest/repositories/creating-and-managing-repositories/about-repositories) -- [Identifying the best authentication method for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise/identifying-the-best-authentication-method-for-your-enterprise) -- [About Enterprise Managed Users](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users) -- [About enterprise policies](https://docs.github.com/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies) -- [Setting policies for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/policies) -- [About billing for your enterprise](https://docs.github.com/enterprise-cloud@latest/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise) -- [About per-user pricing](https://docs.github.com/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/about-per-user-pricing) +- [Choosing an enterprise type for GitHub Enterprise Cloud](https://docs.github.com/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/choose-an-enterprise-type) +- [About Enterprise Managed Users](https://docs.github.com/enterprise-cloud@latest/admin/concepts/identity-and-access-management/enterprise-managed-users) +- [Enterprise policies](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/enterprise-policies) +- [Setting policies for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies) +- [Billing for GitHub Enterprise](https://docs.github.com/enterprise-cloud@latest/billing/concepts/enterprise-billing/billing-for-enterprises) +- [People who consume a license in an organization](https://docs.github.com/enterprise-cloud@latest/billing/reference/github-license-users) - [About rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) -- [Roles in an enterprise](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise) +- [Abilities of roles in an enterprise](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise/abilities-of-roles) - [Roles in an organization](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) -- [Repository roles for an organization](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) -- [About custom repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles) +- [Repository roles for an organization](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) +- [About custom repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles) - [About programmatic access in your organization](https://docs.github.com/enterprise-cloud@latest/organizations/managing-programmatic-access-to-your-organization/about-programmatic-access-in-your-organization) - [Managing your personal access tokens](https://docs.github.com/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) - [About SSH certificate authorities](https://docs.github.com/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) - [About creating GitHub Apps](https://docs.github.com/enterprise-cloud@latest/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) -- [Enforcing policies for GitHub Actions in your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise) -- [About the audit log for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise) +- [Enforcing policies for GitHub Actions in your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise) +- [Audit log for an enterprise](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/audit-log-for-an-enterprise) - [Streaming the audit log for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) - [Displaying IP addresses in the audit log for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise) -- [About custom organization roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles) +- [Permissions of custom organization roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles) - [Managing custom roles for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-roles-in-your-enterprise) - [Managing custom properties for repositories in your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise) -- [Configuring OIDC for Enterprise Managed Users](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users) +- [Configuring OIDC for Enterprise Managed Users](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users) - [About guest collaborators](https://docs.github.com/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators#about-guest-collaborators) - [Managing GitHub Apps for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/managing-github-apps-for-your-enterprise) - [About GitHub Enterprise Cloud with Data Residency](https://docs.github.com/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency) diff --git a/content/library/governance/recommendations/governance-policies-best-practices.md b/content/library/governance/recommendations/governance-policies-best-practices.md index a80b91e..37a7d7e 100644 --- a/content/library/governance/recommendations/governance-policies-best-practices.md +++ b/content/library/governance/recommendations/governance-policies-best-practices.md @@ -78,9 +78,9 @@ For additional topic-specific guidance, see also: Use these key strategies as a baseline to implement GitHub's best practices for governance: -1. [Restrict Actions execution to specific repositories](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization) and not let repo users and owners to arbitrarily create and execute actions workflow. Set this at the **Organization level**. +1. [Restrict Actions execution to specific repositories](https://docs.github.com/enterprise-cloud@latest/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization) and not let repo users and owners to arbitrarily create and execute actions workflow. Set this at the **Organization level**. -2. [Use Actions created by GitHub](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions) and Verified Creators **wherever applicable**. This settings can be enforced at **Enterprise level**. +2. [Use Actions created by GitHub](https://docs.github.com/actions/how-tos/write-workflows/choose-what-workflows-do/find-and-customize-actions) and Verified Creators **wherever applicable**. This settings can be enforced at **Enterprise level**. 3. Default Workflow token permission should be **read-only**: Following the principle of least privilege, it is recommended to set the default workflow token permissions to read-only. Default is read/write, which should be avoided because if a token is compromised, malicious actors can run exploits within the GitHub platform through actions execution. diff --git a/content/library/governance/recommendations/governing-agentic-workflows.md b/content/library/governance/recommendations/governing-agentic-workflows.md index 7c9da8d..806ece1 100644 --- a/content/library/governance/recommendations/governing-agentic-workflows.md +++ b/content/library/governance/recommendations/governing-agentic-workflows.md @@ -250,7 +250,7 @@ With those caveats in mind, here is a practical checklist for teams ready to ado - [APM documentation](https://microsoft.github.io/apm/) - [APM Governance Guide](https://microsoft.github.io/apm/enterprise/governance-guide/) (detailed policy spec, enforcement points, bypass contract) - [APM + gh-aw integration guide](https://microsoft.github.io/apm/integrations/gh-aw/) (the `shared/apm.md` import pattern) -- [APM review panel reference implementation](https://github.com/microsoft/apm/tree/main/.github/skills/apm-review-panel) (credit: Daniel Meppiel) +- [APM review panel reference implementation](https://github.com/microsoft/apm/tree/main/.agents/skills/apm-review-panel) (credit: Daniel Meppiel) - [gh-aw documentation](https://github.github.com/gh-aw/) ## Seeking further assistance diff --git a/content/library/governance/recommendations/governing-agents.md b/content/library/governance/recommendations/governing-agents.md index feb7fee..b40c645 100644 --- a/content/library/governance/recommendations/governing-agents.md +++ b/content/library/governance/recommendations/governing-agents.md @@ -81,7 +81,7 @@ github: ## Scenario overview -Agents — [Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent), [Copilot code review agent](https://docs.github.com/en/copilot/concepts/agents/code-review), and third-party agents like [Anthropic Claude](https://docs.github.com/en/copilot/concepts/agents/anthropic-claude) and [OpenAI Codex](https://docs.github.com/en/copilot/concepts/agents/openai-codex) — are becoming significant contributors to enterprise codebases. GitHub lets teams assign tasks to agents from issues, PRs, and Visual Studio Code in a single workflow. In many organizations, agents already rank among the top contributors by pull request volume. +Agents — [Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent), [Copilot code review agent](https://docs.github.com/copilot/concepts/agents/code-review), and third-party agents like [Anthropic Claude](https://docs.github.com/copilot/concepts/agents/anthropic-claude) and [OpenAI Codex](https://docs.github.com/copilot/concepts/agents/openai-codex) — are becoming significant contributors to enterprise codebases. GitHub lets teams assign tasks to agents from issues, PRs, and Visual Studio Code in a single workflow. In many organizations, agents already rank among the top contributors by pull request volume. This introduces new governance challenges. Agents act faster and at broader scale than any individual. They interact with external services through MCP, use skills to extend their capabilities, and execute code in environments that may hold secrets and infrastructure triggers. A single misconfigured enterprise policy or shared agent definition can affect multiple repositories quickly. @@ -177,7 +177,7 @@ For enterprises managing multiple business units, the question is not _whether_ - Your enterprise uses a **GitHub Enterprise Cloud** environment. - You have **enterprise owner** access to configure policies that cascade to organizations. -- **GitHub Copilot Business or Enterprise** licenses are assigned. See [comparing Copilot plans](https://docs.github.com/en/copilot/get-started/plans#comparing-copilot-plans) for current feature availability by plan. +- **GitHub Copilot Business or Enterprise** licenses are assigned. See [Copilot plans overview](https://docs.github.com/copilot/get-started/plans#copilot-plans-overview) for current feature availability by plan. - **GitHub Actions** is enabled for your enterprise and organizations. The cloud agent runs on Actions runners and consumes Actions minutes. - You have a **SIEM platform** (e.g., Splunk, Microsoft Sentinel, Datadog) capable of ingesting GitHub audit log streams. - Your enterprise already has [foundational code security practices](../../application-security/checklist) in place (CI checks, pull review, secret scanning). Agent governance is an additive layer, not a replacement. @@ -190,16 +190,16 @@ For enterprises managing multiple business units, the question is not _whether_ Navigate to your enterprise settings and click **AI controls**. This centralized pane has three policy surfaces in the sidebar: **Agents**, **Copilot**, and **MCP**. Configure each: -#### Agents → [Copilot cloud agent](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/manage-copilot-coding-agent) +#### Agents → [Copilot cloud agent](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent) - In most enterprises, start with "Let organizations decide" and enable for a pilot group first. - Configure an organization for enterprise custom agents. See section [enterprise custom agents](#enterprise-custom-agents). {{< callout type="info" >}} -Third-party agents have access to the same repositories where the Copilot agent is enabled. See [Enabling or disabling third-party cloud agents](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies#enabling-or-disabling-third-party-coding-agents-in-your-repositories). +Third-party agents have access to the same repositories where the Copilot agent is enabled. See [Enabling or disabling third-party cloud agents](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies#enabling-or-disabling-third-party-coding-agents-in-your-repositories). {{< /callout >}} -#### Copilot → [Policies](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) +#### Copilot → [Policies](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) - Set model access enforcement. Explicitly select which models are allowed. Review the allowlist regularly — enable newly GA models after any required review, and evaluate models' behaviors and use cases to ensure they meet your organization's needs. Deprecated models may be removed; ensure newer or alternative models are enabled before retirement dates. - Enable all Copilot capabilities. Toggle off only if you have a specific requirement to restrict a capability. @@ -216,13 +216,13 @@ Consistent agent behavior requires layered configuration, and over-centralizing #### Repository custom instructions -Create a library of shared [custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) starters. Publish these in a shared repository for teams to reference and consume for their own repository. The following types are supported: +Create a library of shared [custom instructions](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) starters. Publish these in a shared repository for teams to reference and consume for their own repository. The following types are supported: | Type | File | Scope | |------|------|-------| | Repository-wide | `.github/copilot-instructions.md` | All requests in the repository | | Path-specific | `.github/instructions/NAME.instructions.md` | Files matching the `applyTo` glob pattern | -| Agent-specific | `AGENTS.md` (or `CLAUDE.md`, `GEMINI.md`) | See [supported agent-specific file locations](https://docs.github.com/en/copilot/reference/custom-instructions-support) | +| Agent-specific | `AGENTS.md` (or `CLAUDE.md`, `GEMINI.md`) | See [supported agent-specific file locations](https://docs.github.com/copilot/reference/custom-instructions-support) | | Skill definition | `SKILL.md` | Provides specialized domain knowledge and workflows for agents | For example, your instructions might include: @@ -242,24 +242,24 @@ Support for agent-specific instruction files (e.g., `AGENTS.md`, `CLAUDE.md`, `G #### Organization custom instructions -Use [organization custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions) to define a baseline prompt for all users in an organization. Organization owners can configure this in **Organization settings → Copilot → Custom instructions**. Note that organization instructions currently apply to Copilot cloud agent and code review agent on GitHub.com. +Use [organization custom instructions](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-organization-instructions) to define a baseline prompt for all users in an organization. Organization owners can configure this in **Organization settings → Copilot → Custom instructions**. Note that organization instructions currently apply to Copilot cloud agent and code review agent on GitHub.com. Treat these instructions as an organizational baseline — keep them narrow and focused on specific, non-negotiable standards (e.g., security, compliance). Broad or generic org-level instructions add context to every request, consuming tokens without improving results. Layer repository and path-specific instructions for team-level controls where the real effectiveness gains happen. #### Enterprise custom agents -Define enterprise-level agents to deliver consistent and repeatable expertise, behavior, and tool access across all organizations. [Setup enterprise custom agents](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) by creating a `.github-private` repository in a designated organization. Then: +Define enterprise-level agents to deliver consistent and repeatable expertise, behavior, and tool access across all organizations. [Setup enterprise custom agents](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) by creating a `.github-private` repository in a designated organization. Then: 1. Navigate to enterprise → **AI controls** → Custom agents section. 2. Select the source organization containing your `.github-private` repository. 3. Click **Create ruleset** in the "Protect agent files using rulesets" section. -Consider delegating day-to-day agent management to a team of AI managers while maintaining enterprise-owner control over security-sensitive configurations. See [Establish AI managers](https://docs.github.com/en/copilot/tutorials/roll-out-at-scale/establish-ai-managers). +Consider delegating day-to-day agent management to a team of AI managers while maintaining enterprise-owner control over security-sensitive configurations. See [Establish AI managers](https://docs.github.com/copilot/tutorials/roll-out-at-scale/govern-at-scale/establish-ai-managers). Note that agents defined in `.github-private` are org-scoped by default. To make them available enterprise-wide, configure the source organization in enterprise AI controls. Some organizations may intentionally keep certain agents org-scoped rather than promoting them enterprise-wide. {{< callout type="info" >}} -Before deploying a custom agent enterprise-wide, test it in a sandbox repository or with a limited user group. Validate its behavior, then expand. See [Preparing custom agents](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) for rollout guidance. +Before deploying a custom agent enterprise-wide, test it in a sandbox repository or with a limited user group. Validate its behavior, then expand. See [Preparing custom agents](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) for rollout guidance. {{< /callout >}} #### MCP server governance @@ -268,40 +268,40 @@ The [GitHub MCP Registry](https://github.com/mcp) provides a curated list of com 1. Maintain an internal list of reviewed and approved MCP servers with their endpoints, allowed scopes, and review status. 2. Use [rulesets](./managing-repositories-at-scale/rulesets-best-practices) to protect MCP configuration files (`.github/copilot/mcp.json` or `.mcp.json`) in repositories. -3. [Configure an MCP registry](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry) to curate a discoverable set of pre-approved servers. If your policy requires strict control, set the [MCP allowlist policy](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-server-access) to "Registry only." For enterprises where teams need to experiment, use "Allow all" with rulesets on `.github/copilot/mcp.json` and `.mcp.json` (step 2) so changes require review. +3. [Configure an MCP registry](https://docs.github.com/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry) to curate a discoverable set of pre-approved servers. If your policy requires strict control, set the [MCP allowlist policy](https://docs.github.com/copilot/how-tos/administer-copilot/manage-mcp-usage/restrict-based-on-registry) to "Registry only." For enterprises where teams need to experiment, use "Allow all" with rulesets on `.github/copilot/mcp.json` and `.mcp.json` (step 2) so changes require review. -Registry enforcement matches on server name, can be bypassed, and [does not apply to the cloud agent](https://docs.github.com/en/copilot/concepts/mcp-management#supported-surfaces) — treat it as a governance signal and discoverability layer for IDEs, not a hard security boundary. Rulesets on `mcp.json` (step 2) are the primary technical control against unauthorized MCP endpoints across all surfaces except for cloud agent. +Registry enforcement matches on server name, can be bypassed, and [does not apply to the cloud agent](https://docs.github.com/copilot/reference/supported-surfaces-for-policies) — treat it as a governance signal and discoverability layer for IDEs, not a hard security boundary. Rulesets on `mcp.json` (step 2) are the primary technical control against unauthorized MCP endpoints across all surfaces except for cloud agent. {{< callout type="warning" >}} -MCP registry and allowlist enforcement [does not cover all Copilot surfaces](https://docs.github.com/en/copilot/concepts/mcp-management#supported-surfaces). It applies to IDEs (e.g., Visual Studio Code, JetBrains) but **not** to the cloud agent. The cloud agent firewall also [does not apply to MCP servers](#cloud-agent). +MCP registry and allowlist enforcement [does not cover all Copilot surfaces](https://docs.github.com/copilot/reference/supported-surfaces-for-policies). It applies to IDEs (e.g., Visual Studio Code, JetBrains) but **not** to the cloud agent. The cloud agent firewall also [does not apply to MCP servers](#cloud-agent). {{< /callout >}} #### Agent environment standardization -[Customize the agent's development environment](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment) by creating a `.github/workflows/copilot-setup-steps.yml` in each repository. This workflow runs before the agent starts work, giving you deterministic control over the agent's environment. For runner selection, organization admins can set defaults centrally rather than configuring per-repository. +[Configure the development environment](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment) by creating a `.github/workflows/copilot-setup-steps.yml` in each repository. This workflow runs before the agent starts work, giving you deterministic control over the agent's environment. For runner selection, organization admins can set defaults centrally rather than configuring per-repository. -For additional runtime customization, [hooks](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-hooks) let you inject shell commands at key points during agent execution (e.g., formatting, linting, or logging). +For additional runtime customization, [hooks](https://docs.github.com/copilot/concepts/agents/hooks) let you inject shell commands at key points during agent execution (e.g., formatting, linting, or logging). For consistency across similar repositories, share `copilot-setup-steps.yml` examples with company-specific tooling by application type that teams can adapt. Note that reusable workflows are not supported for this file, and composite actions may help share common setup steps. Each repository maintains its own copy. Protect this file with rulesets so changes require review. Organization admins can also [set a default runner and optionally lock it](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent) so the agent runs on a consistent runner across all repositories. #### Use ephemeral runners for agent execution -Use [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) for agent execution. Each job gets a fresh VM that is destroyed after the run, eliminating persistent state and credential leakage between sessions. If you require self-hosted runners, make sure they are ephemeral. +Use [GitHub-hosted runners](https://docs.github.com/actions/concepts/runners/github-hosted-runners) for agent execution. Each job gets a fresh VM that is destroyed after the run, eliminating persistent state and credential leakage between sessions. If you require self-hosted runners, make sure they are ephemeral. ### 3. Enforce security controls and human review gates #### Cloud agent -Copilot cloud agent has [built-in security protections](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent#built-in-security-protections). In the repository's settings, configure additional controls: +Copilot cloud agent has [built-in security protections](https://docs.github.com/copilot/concepts/agents/cloud-agent/risks-and-mitigations). In the repository's settings, configure additional controls: -- **Firewall.** The agent firewall is enabled by default, restricting the agent's internet access to an allowlist. Organization admins can [manage firewall settings across all repositories](https://docs.github.com/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall), enforcing the firewall org-wide so individual repositories cannot disable it, controlling the recommended allowlist, and adding org-wide custom allowlist entries. -- **Recommended allowlist.** Enabled by default, this permits access to OS package repositories, container registries, language package registries, certificate authorities, and other common development dependencies — not only GitHub services. Review the [full list](https://docs.github.com/en/copilot/reference/copilot-allowlist-reference#copilot-cloud-agent-recommended-allowlist). Customize the allowlist to include any internal registries or services your agents need. +- **Firewall.** The agent firewall is enabled by default, restricting the agent's internet access to an allowlist. Organization admins can [manage firewall settings across all repositories](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-the-firewall), enforcing the firewall org-wide so individual repositories cannot disable it, controlling the recommended allowlist, and adding org-wide custom allowlist entries. +- **Recommended allowlist.** Enabled by default, this permits access to OS package repositories, container registries, language package registries, certificate authorities, and other common development dependencies — not only GitHub services. Review the [full list](https://docs.github.com/copilot/reference/copilot-allowlist-reference#copilot-cloud-agent-recommended-allowlist). Customize the allowlist to include any internal registries or services your agents need. {{< callout type="warning" >}} -The cloud agent firewall is limited to [processes started by the agent via its Bash tool](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall#limitations). It does not apply to MCP servers or processes started in agent environment setup. Treat it as one layer of defense, not a comprehensive network boundary. +The cloud agent firewall is limited to [processes started by the agent via its Bash tool](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-the-firewall#limitations). It does not apply to MCP servers or processes started in agent environment setup. Treat it as one layer of defense, not a comprehensive network boundary. {{< /callout >}} -- **Validation tools.** Configure cloud agent to automatically run [code scanning, secret scanning, dependency checks, and Copilot code review](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/configuring-agent-settings) on its changes. +- **Validation tools.** Configure cloud agent to automatically run [built-in code quality and security validation tools](https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/configuring-agent-settings) on its changes. #### Code review agent @@ -320,13 +320,13 @@ applyTo: '**' - Suggest improvements for naming, readability, and minor convention deviations — but do not block merge. ``` -See [Use custom instructions](https://docs.github.com/en/copilot/tutorials/use-custom-instructions) and [github/awesome-copilot](https://github.com/github/awesome-copilot/tree/main/instructions) examples. +See [Use custom instructions for Copilot code review](https://docs.github.com/copilot/tutorials/customize-code-review) and [github/awesome-copilot](https://github.com/github/awesome-copilot/tree/main/instructions) examples. #### Protect agentic primitive files with rulesets Agent configuration files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md`), skill configuration files (`SKILL.md`), MCP configuration files (`mcp.json`), and the `.github-private` repository for enterprise custom agents define what agents can do and which tools they can access. Unauthorized modifications can change agent behaviors. -Apply [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) to these files so changes require human review before taking effect. +Apply [rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) to these files so changes require human review before taking effect. ### 4. Build agent observability and audit pipeline @@ -334,7 +334,7 @@ Enterprise owners have two complementary surfaces for monitoring agent activity: #### Audit log streaming: for retention, correlation, and anomaly detection -[Stream audit logs](https://docs.github.com/en/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) to your SIEM platform for long-term retention and correlation. Audit logs capture specific agent and management activities — session creation, commits, PR activity, and policy changes — not the step-by-step session transcript. [Agentic audit log events](https://docs.github.com/en/copilot/reference/agentic-audit-log-events) such as `action`, `actor_is_agent`, `agent_session_id`, and `user` are the key fields for correlations and anomaly detection. +[Stream audit logs](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) to your SIEM platform for long-term retention and correlation. Audit logs capture specific agent and management activities — session creation, commits, PR activity, and policy changes — not the step-by-step session transcript. [Audit log events for agents](https://docs.github.com/copilot/reference/enterprise-administrators/agentic-audit-log-events) such as `action`, `actor_is_agent`, `agent_session_id`, and `user` are the key fields for correlations and anomaly detection. **What to monitor in your SIEM:** @@ -342,7 +342,7 @@ Enterprise owners have two complementary surfaces for monitoring agent activity: |--------|-----------------------|----------------| | Agent sessions per user per day | `agent_session_id`, `user` | Detect anomalous usage or compromised accounts | | MCP policy changes | `copilot.mcp_*` actions | Identify unauthorized changes to approved tool integrations | -| Agent changes to high-risk files (workflows, MCP config, agent instructions) | `git.push`, `pull_request.*` with `actor_is_agent` | High-risk modifications that could affect CI/CD pipelines or agent behavior. Correlate audit events with [webhook payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push) for file-level detail | +| Agent changes to high-risk files (workflows, MCP config, agent instructions) | `git.push`, `pull_request.*` with `actor_is_agent` | High-risk modifications that could affect CI/CD pipelines or agent behavior. Correlate audit events with [webhook payloads](https://docs.github.com/webhooks/webhook-events-and-payloads#push) for file-level detail | | Changes to environment secrets used by agents | `environment.*` actions | Could alter what agents can access or authenticate to | | Bypass events on rulesets | `repository_ruleset.*` with `actor_is_agent` | Detect attempts to circumvent governance controls | @@ -354,7 +354,7 @@ Session transcripts give you what audit logs cannot: the agent's reasoning, the - **Spot-check agent sessions.** Schedule periodic transcript reviews for repos that hold secrets, infrastructure-as-code, or CI/CD workflows. Look for patterns: agents modifying files outside their scope, retrying failed commands in loops, or ignoring custom instruction guardrails. - **Validate new configurations.** After changing custom instructions, `copilot-setup-steps.yml`, or MCP server access, review a few transcripts to confirm agents behave as expected. -Enterprise administrators can review sessions from the last 28 days in **AI controls → Agent sessions**. Each repository also has an **Agents** tab where maintainers can watch past and current sessions in progress. See [Monitoring agentic activity](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity). +Enterprise administrators can review sessions from the last 28 days in **AI controls → Agent sessions**. Each repository also has an **Agents** tab where maintainers can watch past and current sessions in progress. See [Monitoring agentic activity](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity). {{< callout type="info" >}} Session transcripts are available only through the GitHub UI — they cannot be streamed to a SIEM or retrieved via API. @@ -364,12 +364,12 @@ Agent-generated code, custom instructions, and MCP configurations should be revi ### 5. Manage agent-related costs -Copilot agents consume both [GitHub Actions minutes and premium requests](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/about-billing-for-github-copilot#allowance-usage-for-copilot-coding-agent). Standard runners consume your monthly Actions allowance at no additional cost; larger runners incur a per-minute charge. Agent sessions can run for up to 59 minutes. Without spending limits, agent-driven spending can accumulate quickly and be difficult to attribute to specific cost owners. +Copilot agents consume both [GitHub Actions minutes and AI credits](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent#copilot-cloud-agent-usage-costs). Standard runners consume your monthly Actions allowance at no additional cost; larger runners incur a per-minute charge. Agent sessions can run for up to 59 minutes. Without spending limits, agent-driven spending can accumulate quickly and be difficult to attribute to specific cost owners. **What makes agent cost governance different:** - **Actions minutes add up.** Each agent session consumes GitHub Actions minutes for the duration of the agent's work. Monitor Actions usage to ensure agent workloads do not impact your CI/CD capacity. -- **Model selection amplifies cost.** Different models have different [request multipliers](https://docs.github.com/en/copilot/concepts/billing/copilot-requests). Factor model choice into your cost governance. +- **Model selection amplifies cost.** Different models have different [pricing](https://docs.github.com/copilot/reference/copilot-billing/models-and-pricing). Factor model choice into your cost governance. For detailed guidance on budget configuration, cost center allocation, user-level budgets, and cost attribution — see [Managing AI credits with FinOps principles](./managing-ai-credits). @@ -418,26 +418,26 @@ Review quality depends heavily on custom instructions. Without instructions, rev ### External resources -- [Managing enterprise Copilot policies](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) — model access enforcement and capability toggles -- [Establish AI managers](https://docs.github.com/en/copilot/tutorials/roll-out-at-scale/establish-ai-managers) — delegating day-to-day agent management with custom roles -- [Adding repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) — `.github/copilot-instructions.md` and path-specific instruction files -- [Adding organization custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-organization-instructions) — baseline prompts for all users in an organization -- [Support for different types of custom instructions](https://docs.github.com/en/copilot/reference/custom-instructions-support) — which agent-specific instruction are supported in which environments -- [Managing Copilot coding agent for your enterprise](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/manage-copilot-coding-agent) — enable or disable the cloud agent and configure third-party agent defaults -- [Preparing custom agents for your enterprise](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) — setting up `.github-private` and rolling out enterprise custom agents +- [Managing enterprise Copilot policies](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) — model access enforcement and capability toggles +- [Establish AI managers](https://docs.github.com/copilot/tutorials/roll-out-at-scale/govern-at-scale/establish-ai-managers) — delegating day-to-day agent management with custom roles +- [Adding repository custom instructions](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions) — `.github/copilot-instructions.md` and path-specific instruction files +- [Adding organization custom instructions](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-organization-instructions) — baseline prompts for all users in an organization +- [Support for different types of custom instructions](https://docs.github.com/copilot/reference/custom-instructions-support) — which agent-specific instruction are supported in which environments +- [Enabling Copilot cloud agent in your enterprise](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent) — enable or disable the cloud agent and configure third-party agent defaults +- [Preparing custom agents for your enterprise](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents) — setting up `.github-private` and rolling out enterprise custom agents - [github/awesome-copilot](https://github.com/github/awesome-copilot) — curated collection of custom instructions, agents, and Copilot configuration examples -- [About MCP and Copilot](https://docs.github.com/en/copilot/concepts/context/mcp) — conceptual overview of Model Context Protocol integration in GitHub Copilot -- [Configure an MCP registry](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry) — curating a discoverable set of pre-approved MCP servers -- [Configure MCP server access](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-server-access) — allowlist policies for MCP server usage +- [About MCP and Copilot](https://docs.github.com/copilot/concepts/context/mcp) — conceptual overview of Model Context Protocol integration in GitHub Copilot +- [Configure an MCP registry](https://docs.github.com/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry) — curating a discoverable set of pre-approved MCP servers +- [Restrict MCP server access to a custom registry](https://docs.github.com/copilot/how-tos/administer-copilot/manage-mcp-usage/restrict-based-on-registry) — allowlist policies for MCP server usage - [Model Context Protocol specification](https://modelcontextprotocol.io/) — protocol documentation for understanding MCP capabilities and security considerations - [GitHub MCP Server Policies and Governance](https://github.com/github/github-mcp-server/blob/main/docs/policies-and-governance.md) — control mechanisms for the GitHub MCP server in third-party host applications -- [About Copilot cloud agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) — capabilities, built-in security protections, and operational model of the cloud agent -- [Copilot code review agent](https://docs.github.com/en/copilot/concepts/agents/code-review) — automatic and on-demand code review powered by Copilot -- [Customizing the cloud agent environment](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment) — configuring `copilot-setup-steps.yml` to standardize agent runtime environments -- [About hooks](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-hooks) — injecting shell commands at key points during agent execution -- [Customizing the agent firewall](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-firewall) — managing the agent network allowlist at org and repo level -- [Configuring agent settings](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/configuring-agent-settings) — enabling code scanning, secret scanning, and dependency checks on agent changes -- [Monitoring agentic activity](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity) — enterprise session monitoring UI for real-time agent oversight -- [Agentic audit log events](https://docs.github.com/en/copilot/reference/agentic-audit-log-events) — reference for agent-specific audit log fields used for SIEM correlation and anomaly detection -- [Streaming the audit log for your enterprise](https://docs.github.com/en/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) — configuring audit log streaming to external SIEM platforms -- [Managing your GitHub Copilot usage and spending](https://docs.github.com/en/billing/using-the-new-billing-platform/managing-billing-for-your-products/managing-your-github-copilot-usage-and-spending) — budget configuration, spending limits, and alerting thresholds in the billing platform +- [About Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent) — capabilities, built-in security protections, and operational model of the cloud agent +- [Copilot code review agent](https://docs.github.com/copilot/concepts/agents/code-review) — automatic and on-demand code review powered by Copilot +- [Configure the development environment](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment) — configuring `copilot-setup-steps.yml` to standardize agent runtime environments +- [About hooks](https://docs.github.com/copilot/concepts/agents/hooks) — injecting shell commands at key points during agent execution +- [Customizing the agent firewall](https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-the-firewall) — managing the agent network allowlist at org and repo level +- [Configuring agent settings](https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/configuring-agent-settings) — enabling built-in code quality and security validation tools on agent changes +- [Monitoring agentic activity](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity) — enterprise session monitoring UI for real-time agent oversight +- [Audit log events for agents](https://docs.github.com/copilot/reference/enterprise-administrators/agentic-audit-log-events) — reference for agent-specific audit log fields used for SIEM correlation and anomaly detection +- [Streaming the audit log for your enterprise](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) — configuring audit log streaming to external SIEM platforms +- [Manage and monitor spending for GitHub Copilot](https://docs.github.com/copilot/how-tos/manage-and-track-spending) — tracking Copilot usage, AI credit consumption, and company spending diff --git a/content/library/governance/recommendations/managing-ai-credits.md b/content/library/governance/recommendations/managing-ai-credits.md index b9b19c9..52180fe 100644 --- a/content/library/governance/recommendations/managing-ai-credits.md +++ b/content/library/governance/recommendations/managing-ai-credits.md @@ -662,7 +662,7 @@ Enterprise team membership and cost center ULBs can be managed at scale through ### Budget evaluation order -Refer to [Budget evaluation order](https://docs.github.com/enterprise-cloud@latest/copilot/tutorials/budgets/optimizing-your-budget-configuration#budget-evaluation-order) +Refer to [How billing flows through budgets](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/billing/budgets-for-usage-based-billing#how-billing-flows-through-budgets) for the sequence GitHub uses to evaluate AI credit controls and budgets. Treat the applicable budgets as concurrent guardrails. Remaining capacity at @@ -682,16 +682,16 @@ budgets to avoid unintended interruptions. - [AI usage report](https://docs.github.com/billing/reference/billing-reports#ai-usage-report) - [Auto model selection](https://docs.github.com/copilot/concepts/models/auto-model-selection) -- [Budget evaluation order](https://docs.github.com/enterprise-cloud@latest/copilot/tutorials/budgets/optimizing-your-budget-configuration#budget-evaluation-order) - [FinOps Framework](https://learn.microsoft.com/en-us/cloud-computing/finops/framework/finops-framework) - [GitHub REST API: Billing budgets](https://docs.github.com/enterprise-cloud@latest/rest/billing/budgets?apiVersion=2026-03-10) +- [How billing flows through budgets](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/billing/budgets-for-usage-based-billing#how-billing-flows-through-budgets) - [Included usage controls for cost centers](https://docs.github.com/copilot/concepts/billing/budgets-for-usage-based-billing#included-usage-controls-for-cost-centers) - [Models comparison](https://docs.github.com/copilot/reference/ai-models/model-comparison) - [Models and pricing for GitHub Copilot](https://docs.github.com/copilot/reference/copilot-billing/models-and-pricing) - [Monitoring your GitHub Copilot usage and entitlements](https://docs.github.com/copilot/how-tos/manage-and-track-spending/monitor-ai-usage) - [Optimizing your budget configuration](https://docs.github.com/enterprise-cloud@latest/copilot/tutorials/budgets/optimizing-your-budget-configuration) -- [Prepare for usage-based billing](https://docs.github.com/copilot/how-tos/manage-and-track-spending/prepare-for-usage-based-billing) - [Setting an AI credit session limit](https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit) - [Understanding Copilot budgeting](https://support.github.com/product-guides/github-copilot/get-started/understanding-copilot-budgeting) - [Update your IDE, client, and extension](https://docs.github.com/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises#update-your-ide-client-and-extension) +- [Usage-based billing for organizations and enterprises](https://docs.github.com/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises) - [Viewing usage in your IDE](https://docs.github.com/copilot/how-tos/manage-and-track-spending/monitor-ai-usage#viewing-usage-in-your-ide) diff --git a/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md b/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md index 99a88d5..9ec4c75 100644 --- a/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md +++ b/content/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices.md @@ -179,7 +179,7 @@ Recommended rules include (see [Available rules for rulesets](https://docs.githu - **Block force pushes & deletions** - These protect against accidental or malicious destruction of commit history, ensuring code changes remain auditable and recoverable. Force pushes can overwrite colleagues' work and break CI/CD pipelines that rely on stable commit references. - **Require a pull request before merging** - This establishes a minimal review gate that creates visibility into all changes, enables automated checks to run, and provides an opportunity for knowledge sharing even if formal approval isn't required at this tier. -- **Require workflows to pass (e.g. central security/compliance workflow once stable inclusive of [Dependency Review](https://docs.github.com/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review))** - Automated security scanning catches common vulnerabilities before they enter the main branch, reducing remediation costs. Dependency Review specifically prevents introduction of known-vulnerable packages that could compromise the entire software supply chain. +- **Require workflows to pass (e.g. central security/compliance workflow once stable inclusive of [Dependency Review](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/supply-chain-security/dependency-review))** - Automated security scanning catches common vulnerabilities before they enter the main branch, reducing remediation costs. Dependency Review specifically prevents introduction of known-vulnerable packages that could compromise the entire software supply chain. ### 3. Production tier ruleset @@ -194,7 +194,7 @@ Applied where repository supports a production application (e.g. custom property - **Require approval of the most recent reviewable push** - Guarantees that approvals correspond to the latest reviewed commit. - **Require conversation resolution before merging** - Ensures reviewer feedback is addressed and reduces the risk of overlooked issues. - **Automatically request [Copilot code review](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review?tool=webui)** - Adds an automated review layer to surface potential issues quickly and at scale. -- **Require code scanning results (severity threshold tuned to avoid overly cautious blocks)** - Integrates automated security scanning (e.g. [CodeQL](https://docs.github.com/enterprise-cloud@latest/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)) to catch vulnerabilities prior to merging while tuning thresholds to reduce noisy false positives. +- **Require code scanning results (severity threshold tuned to avoid overly cautious blocks)** - Integrates automated security scanning (e.g. [CodeQL](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/code-scanning/codeql/codeql-code-scanning)) to catch vulnerabilities prior to merging while tuning thresholds to reduce noisy false positives. ### 4. Sensitive / regulated tier ruleset diff --git a/content/library/overview/overview.md b/content/library/overview/overview.md index 6dd86ce..0c2646e 100644 --- a/content/library/overview/overview.md +++ b/content/library/overview/overview.md @@ -108,9 +108,9 @@ Finally, we have Services, Support, and Partners ready to assist you at every st ## Related Links -- [GitHub Docs](https://docs.github.com/) +- [GitHub Docs](https://docs.github.com) - [GitHub Skills](https://skills.github.com/) -- [GitHub Security Features](https://github.com/features/security) +- [GitHub Advanced Security](https://docs.github.com/get-started/learning-about-github/about-github-advanced-security) - [GitHub Enterprise](https://github.com/enterprise) This framework is a living document, designed to evolve with advancements in technology, changes in best practices, and the feedback from the community. It serves as a flexible guide, supplementing GitHub's official documentation, and can be adapted to meet the unique needs of each organization. diff --git a/content/library/productivity/design-principles.md b/content/library/productivity/design-principles.md index 419933b..94f73af 100644 --- a/content/library/productivity/design-principles.md +++ b/content/library/productivity/design-principles.md @@ -180,7 +180,7 @@ Engineering system success refers to the ability of teams to achieve their engin Success requires a structured, data-driven approach by iteratively identifying barriers, implementing targeted interventions, and continuously monitoring progress. It emphasizes systems thinking, sustainability, and balancing short-term wins with long-term impacts. -This principle is adapted from the three steps in the [Engineering System Success Playbook](https://resources.github.com/engineering-system-success-playbook/), which guides improvement across four primary engineering system zones: quality, velocity, developer happiness, and business outcomes. +This principle is adapted from the three steps in the [Engineering System Success Playbook](https://github.com/resources/insights/engineering-system-success-playbook), which guides improvement across four primary engineering system zones: quality, velocity, developer happiness, and business outcomes. ### Start diff --git a/content/library/productivity/quick-links.md b/content/library/productivity/quick-links.md index 7b883ca..1016913 100644 --- a/content/library/productivity/quick-links.md +++ b/content/library/productivity/quick-links.md @@ -11,15 +11,15 @@ A curated list of resources and tools to enhance productivity across the **Produ ## Automation -- [GitHub Actions Documentation](https://docs.github.com/en/actions) -- [CI/CD with GitHub Actions](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) -- [Automating Workflows with GitHub Actions](https://docs.github.com/en/actions/learn-github-actions) +- [GitHub Actions Documentation](https://docs.github.com/actions) +- [Continuous integration with GitHub Actions](https://docs.github.com/actions/get-started/continuous-integration) +- [Writing workflows with GitHub Actions](https://docs.github.com/actions/how-tos/write-workflows) - [Getting Started with DevOps Automation](https://github.blog/enterprise-software/devops/getting-started-with-devops-automation/) ## Integration -- [GitHub API Documentation](https://docs.github.com/en/rest) -- [Integrating with GitHub](https://docs.github.com/en/get-started/exploring-integrations/about-building-integrations) +- [GitHub API Documentation](https://docs.github.com/rest) +- [Integrating with GitHub](https://docs.github.com/integrations/concepts/about-building-integrations) - [GitHub Marketplace](https://github.com/marketplace) ## Continuous Learning @@ -31,7 +31,7 @@ A curated list of resources and tools to enhance productivity across the **Produ ## Feedback -- [Use GitHub Discussions to gather feedback](https://docs.github.com/en/discussions) -- [Creating and Managing Issues on GitHub](https://docs.github.com/en/issues) -- [User Feedback Best Practices](https://www.usability.gov/how-to-and-tools/methods/collecting-user-feedback.html) +- [Use GitHub Discussions to gather feedback](https://docs.github.com/discussions) +- [Creating and Managing Issues on GitHub](https://docs.github.com/issues) +- [User research](https://digital.gov/topics/research) - [Microsoft Forms for Collecting Feedback](https://www.microsoft.com/en-us/microsoft-365/online-surveys-polls-quizzes) diff --git a/content/library/productivity/recommendations/adopting-copilot-at-scale.md b/content/library/productivity/recommendations/adopting-copilot-at-scale.md index 83e2844..3a46bc0 100644 --- a/content/library/productivity/recommendations/adopting-copilot-at-scale.md +++ b/content/library/productivity/recommendations/adopting-copilot-at-scale.md @@ -88,7 +88,7 @@ A few key strategies can help you maximize the benefits from your investment in ## Assumptions and preconditions -1. [GitHub Enterprise Cloud (GHEC)](https://docs.github.com/en/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) +1. [GitHub Enterprise Cloud (GHEC)](https://docs.github.com/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) 2. Either GitHub Copilot Enterprise or GitHub Copilot Business ([GitHub Copilot plans](https://github.com/features/copilot/plans)) ## Recommended deployment @@ -101,7 +101,7 @@ An example GitHub Copilot launch plan should include the following minimum eleme #### Pre-launch -- Set up [GitHub Copilot policies](https://docs.github.com/en/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise) for your Enterprise and/or Organization(s) +- Set up [GitHub Copilot policies](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise) for your Enterprise and/or Organization(s) - Establish a user onboarding process that enables self-service access to GitHub Copilot to reduce manual overhead - Communicate the launch date of GitHub Copilot to your organization - Create a channel of communication for technical challenges and feedback @@ -111,7 +111,7 @@ An example GitHub Copilot launch plan should include the following minimum eleme #### Launch week (week 0) - Communicate the opportunity, benefits, and availability of GitHub Copilot to your organization -- Provide on-demand [training](https://learn.microsoft.com/en-us/training/modules/introduction-to-github-copilot/) and [resources](https://docs.github.com/en/enterprise-cloud@latest/copilot/get-started/quickstart) for users to get started with GitHub Copilot +- Provide on-demand [training](https://learn.microsoft.com/en-us/training/modules/introduction-to-github-copilot/) and [resources](https://docs.github.com/enterprise-cloud@latest/copilot/get-started/quickstart) for users to get started with GitHub Copilot #### Post-launch (weeks 1-4) @@ -122,7 +122,7 @@ An example GitHub Copilot launch plan should include the following minimum eleme #### Post-launch (weeks 5-8) - Monitor GitHub Copilot adoption and activity metrics -- Develop a GitHub Copilot reporting mechanism to track KPIs and derive meaningful insights about GitHub Copilot by using the [Copilot usage metrics API](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28) and [Copilot User Management API](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-user-management?apiVersion=2022-11-28) +- Develop a GitHub Copilot reporting mechanism to track KPIs and derive meaningful insights about GitHub Copilot by using the [Copilot usage metrics API](https://docs.github.com/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28) and [Copilot User Management API](https://docs.github.com/enterprise-cloud@latest/rest/copilot/copilot-user-management?apiVersion=2022-11-28) - Build on your GitHub Copilot Expert Hub with advanced training and resources specific to your organization - Gather feedback from users and iterate on your GitHub Copilot program @@ -143,10 +143,10 @@ However, it is impractical to expect every user across large organizations to be GitHub offers many free resources to help users get started with GitHub Copilot: - [GitHub Copilot Fundamentals Course via Microsoft Learn](https://learn.microsoft.com/en-us/training/paths/copilot/) -- [GitHub Copilot Learning Pathway](https://resources.github.com/learn/pathways/copilot/essentials/essentials-of-github-copilot/) +- [GitHub Copilot Learning Pathway](https://learn.github.com/learning-pathways/github-copilot) - [GitHub Copilot Youtube Playlist](https://www.youtube.com/playlist?list=PL0lo9MOBetEHEHi9h0k_lPn0XZdEeYZDS) - [GitHub Copilot Blog Posts](https://github.blog/?s=copilot) -- [GitHub Copilot Quickstart Documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/get-started/quickstart) +- [GitHub Copilot Quickstart Documentation](https://docs.github.com/enterprise-cloud@latest/copilot/get-started/quickstart) To best prepare your existing team and future hires, consider offering a mix of instructor-led and on-demand Copilot enablement resources. @@ -154,7 +154,7 @@ To best prepare your existing team and future hires, consider offering a mix of Building an internal GitHub Copilot community can help users share best practices, success stories, and helpful resources. An internal GitHub Copilot community can also help users connect with others who are using GitHub Copilot in similar ways, and can provide a forum for users to ask questions and share feedback. -A devoted GitHub repository or organization, along with GitHub native features like [GitHub Discussions](https://docs.github.com/en/enterprise-cloud@latest/discussions/quickstart), can be used to denote answers to frequently asked questions, foster collaboration, and collect innovative ideas from your GitHub Copilot community. +A devoted GitHub repository or organization, along with GitHub native features like [GitHub Discussions](https://docs.github.com/enterprise-cloud@latest/discussions/quickstart), can be used to denote answers to frequently asked questions, foster collaboration, and collect innovative ideas from your GitHub Copilot community. Be sure to include other helpful resources for your GitHub Copilot community, such as: @@ -184,7 +184,7 @@ GitHub Copilot licenses can be assigned in a few different ways, each with their 3) Specific teams in an organization 4) Specific teams in an enterprise -While assigning licenses out of a single organization can simplify license management, it restricts the granularity of Copilot telemetry data from the [Copilot usage metrics API](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics). +While assigning licenses out of a single organization can simplify license management, it restricts the granularity of Copilot telemetry data from the [Copilot usage metrics API](https://docs.github.com/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics). If you would like to track GitHub Copilot usage across your GitHub Organizations, consider assigning licenses to specific teams or individuals in those organizations. @@ -197,7 +197,7 @@ When a user receives a seat from multiple organizations in the same enterprise, When you've enabled GitHub 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 Copilot quickly. -For examples of license automation, see [Setting up a self-serve process for GitHub Copilot licenses](https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/roll-out-at-scale/assign-licenses/set-up-self-serve-licenses) and [Reminding inactive users to use their GitHub Copilot license](https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/roll-out-at-scale/assign-licenses/remind-inactive-users). +For examples of license automation, see [Setting up a self-serve process for GitHub Copilot licenses](https://docs.github.com/enterprise-cloud@latest/copilot/tutorials/roll-out-at-scale/assign-licenses/set-up-self-serve-licenses) and [Reminding inactive users to use their GitHub Copilot license](https://docs.github.com/enterprise-cloud@latest/copilot/tutorials/roll-out-at-scale/assign-licenses/remind-inactive-users). ### Automating license revocation diff --git a/content/library/productivity/recommendations/engineering-system-metrics.md b/content/library/productivity/recommendations/engineering-system-metrics.md index 56e6c54..c77f4ef 100644 --- a/content/library/productivity/recommendations/engineering-system-metrics.md +++ b/content/library/productivity/recommendations/engineering-system-metrics.md @@ -148,4 +148,4 @@ Strike a pragmatic balance between measurement effort and benefits by implementi -Explore further on four zones and twelve metrics in the [Engineering System Success Playbook](https://resources.github.com/engineering-system-success-playbook/). +Explore further on four zones and twelve metrics in the [Engineering System Success Playbook](https://github.com/resources/insights/engineering-system-success-playbook). diff --git a/content/library/scenarios/measuring-genai-impact.md b/content/library/scenarios/measuring-genai-impact.md index 5b63078..38505bf 100644 --- a/content/library/scenarios/measuring-genai-impact.md +++ b/content/library/scenarios/measuring-genai-impact.md @@ -39,7 +39,7 @@ Organizations should establish a comprehensive measurement strategy that capture Effective implementation requires that users receive appropriate access to GenAI tools governed by enterprise guardrails. Track metrics such as license activation rate and onboarding completion. -For Copilot, [GitHub Enterprise settings](https://docs.github.com/en/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise) helps Copilot stay compliant with organizational policies, and the [User Management REST API](https://docs.github.com/en/rest/copilot/copilot-user-management?apiVersion=2022-11-28) provides quantitative tracking of license activations. +For Copilot, [GitHub Enterprise settings](https://docs.github.com/enterprise-cloud@latest/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) helps Copilot stay compliant with organizational policies, and the [User Management REST API](https://docs.github.com/rest/copilot/copilot-user-management?apiVersion=2022-11-28) provides quantitative tracking of license activations. **Implementation Control Checklist:** @@ -59,7 +59,7 @@ Track feature utilization and engagement patterns through both qualitative and q We measure by asking for users' direct feedback on GenAI impact on their professional efficiency. This may come in the form of focus sessions, 1:1s, structured questionnaires or polls, and incorporating into existing [developer experience surveys](https://github.com/github/copilot-survey-engine). **Quantitative Measurement:** -Track feature utilization and engagement patterns to identify adoption trends and potential barriers. For Copilot, the [Metrics REST API](https://docs.github.com/en/rest/copilot/copilot-metrics?apiVersion=2022-11-28) provides detailed insights on usage patterns, allowing organizations to monitor and analyze adoption pattern: +Track feature utilization and engagement patterns to identify adoption trends and potential barriers. For Copilot, the [Metrics REST API](https://docs.github.com/rest/copilot/copilot-usage-metrics?apiVersion=2026-03-10) provides detailed insights on usage patterns, allowing organizations to monitor and analyze adoption pattern: - Code suggestion and acceptance rate - IDE-specific usage @@ -108,4 +108,4 @@ Common business challenges where Copilot may assist: -Read more about measuring GenAI impact in the [Engineering System Success Playbook](https://resources.github.com/engineering-system-success-playbook/). +Read more about measuring GenAI impact in the [Engineering System Success Playbook](https://github.com/resources/insights/engineering-system-success-playbook). diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/02-source-environment-assessment.md b/content/library/scenarios/migrations/azure-devops-migration-guide/02-source-environment-assessment.md index 02a196e..b119f69 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/02-source-environment-assessment.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/02-source-environment-assessment.md @@ -37,7 +37,7 @@ Use this checklist to help guide your assessment: Before you start, review these resources to support your assessment: - **GitHub documentation** - - [About migrations from Azure DevOps to GitHub Enterprise Cloud](https://docs.github.com/enterprise-cloud@latest/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud) + - [Understand migrations from Azure DevOps to GitHub](https://docs.github.com/enterprise-cloud@latest/migrations/ado/understand-migrations-from-azure-devops-to-github) - [Building a migration inventory](https://docs.github.com/migrations/overview/planning-your-migration-to-github#building-a-basic-inventory-of-the-repositories-you-want-to-migrate) - **Microsoft Learn** - [About GitHub integration with Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/cross-service/github-integration?view=azure-devops) @@ -99,8 +99,8 @@ Analyzing repositories helps you plan migration batches and identify challenges The GitHub Enterprise Importer (GEI) tool provides a starting point. Before running the tool, ensure you have credentials configured for Azure DevOps and GitHub: -- [Personal Access Tokens Guidance for GitHub](https://docs.github.com/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-github) -- [Personal Access Tokens Guidance for Azure DevOps](https://docs.github.com/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) +- [Personal Access Tokens Guidance for GitHub](https://docs.github.com/migrations/ado/manage-access#create-a-personal-access-token-classic-on-github) +- [Personal Access Tokens Guidance for Azure DevOps](https://docs.github.com/migrations/ado/manage-access#create-a-personal-access-token-on-azure) With configured credentials, use this command to generate an inventory report of your Azure DevOps environment: @@ -199,9 +199,9 @@ Use this table to map your Azure DevOps permissions to their GitHub equivalents: | Azure DevOps | GitHub | |--------------|--------| | Project Collection Administrators | [Organization Owner](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) | -| Project Administrators | [Repository Admin role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | -| Contributors | [Repository Write role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | -| Readers | [Repository Read role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | +| Project Administrators | [Repository Admin role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | +| Contributors | [Repository Write role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | +| Readers | [Repository Read role](https://docs.github.com/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) via [Organization Teams](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | | Branch Policies | [Repository Rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | {{< callout type="info" >}} @@ -227,8 +227,8 @@ Understanding your security and compliance requirements ensures your GitHub envi - Authentication methods - Ensures proper identity management transition - Authorization policies - Maintains access control consistency - [IP allow lists](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) - Preserves network security boundaries - - [Secret scanning](https://docs.github.com/enterprise-cloud@latest/code-security/secret-scanning/about-secret-scanning) - Enhances security with GitHub's advanced capabilities _(requires GitHub Secret Protection for private repositories)_ - - [Code scanning](https://docs.github.com/enterprise-cloud@latest/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) - Leverages GitHub's security features _(requires GitHub Code Security for private repositories)_ + - [Secret scanning](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/secret-security/secret-scanning) - Enhances security with GitHub's advanced capabilities _(requires GitHub Secret Protection for private repositories)_ + - [Code scanning](https://docs.github.com/enterprise-cloud@latest/code-security/concepts/code-scanning/code-scanning) - Leverages GitHub's security features _(requires GitHub Code Security for private repositories)_ - Security notifications - Ensures proper alerting workflows ### Compliance assessment @@ -237,7 +237,7 @@ Understanding your security and compliance requirements ensures your GitHub envi - Audit logging needs - Ensures regulatory compliance continuity - Retention policies - Maintains data governance requirements - Access controls - Preserves security compliance - - [Security hardening](https://docs.github.com/enterprise-cloud@latest/admin/configuration/hardening-security-for-your-enterprise) - Implements GitHub security best practices + - [Security hardening](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings/hardening-security-for-your-enterprise) - Implements GitHub security best practices - Approval workflows - Maintains governance controls ## Migration impact analysis @@ -278,7 +278,7 @@ Understanding performance factors helps optimize the migration process: ### API and rate limits - **Service boundaries** - - [ ] [GitHub API rate limits](https://docs.github.com/enterprise-cloud@latest/rest/overview/rate-limits-for-the-rest-api) _(plans migration pace)_ + - [ ] [GitHub API rate limits](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api) _(plans migration pace)_ - [ ] [Azure DevOps API rate limits](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/rate-limits?view=azure-devops) _(prevents interruptions)_ - [ ] Concurrent migration capacity _(optimizes throughput)_ - [ ] Migration tool throttling _(ensures reliability)_ @@ -304,7 +304,7 @@ Understanding performance factors helps optimize the migration process: After completing your environment assessment: -1. Review the [GitHub Well-Architected Framework](https://wellarchitected.github.com/library/governance/checklist/) for governance planning +1. Review the [Checklist for Governance](https://learn.github.com/well-architected/library/governance/checklist/) for governance planning 2. Proceed to [Target Environment Setup](./setup) to prepare your GitHub Enterprise Cloud environment {{< callout type="info" >}} diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/03-target-environment.md b/content/library/scenarios/migrations/azure-devops-migration-guide/03-target-environment.md index e77c191..e1eddff 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/03-target-environment.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/03-target-environment.md @@ -38,18 +38,18 @@ Use this checklist to help guide your setup: Before configuring your target environment, review these resources: - **GitHub documentation** - - [Enterprise configuration guide](https://docs.github.com/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise) - - [Identity and access management](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise) + - [Enterprise configuration guide](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings) + - [Understanding IAM for enterprises](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises) - [Organization security features](https://docs.github.com/enterprise-cloud@latest/organizations/keeping-your-organization-secure) -- [Essentials of administration and governance with GitHub Enterprise Cloud](https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/) +- [Essentials of governance and administration with GitHub Enterprise](https://learn.github.com/well-architected/library/governance/recommendations/governance-administration-essentials/) - **Microsoft Learn** - [GitHub administration and product features](https://learn.microsoft.com/en-us/training/paths/github-administration-products/) - [GitHub foundations - part 1](https://learn.microsoft.com/en-us/training/paths/github-foundations/) - [GitHub foundations - part 2](https://learn.microsoft.com/en-us/training/paths/github-foundations-2/) - **Well-Architected Framework** - - [Getting started with GitHub Well-Architected](https://wellarchitected.github.com/library/overview/getting-started-checklist/) - - [Governance checklist](https://wellarchitected.github.com/library/governance/checklist/) - - [Security pillar](https://wellarchitected.github.com/pillars/security/) + - [Getting started with GitHub Well-Architected](https://learn.github.com/well-architected/library/overview/getting-started-checklist/) + - [Governance checklist](https://learn.github.com/well-architected/library/governance/checklist/) + - [Security pillar](https://learn.github.com/well-architected/library/application-security/) ## Enterprise configuration @@ -57,7 +57,7 @@ Before configuring your target environment, review these resources: Setting up proper authentication and access controls is essential for a successful migration. -- [ ] [Configure enterprise settings](https://docs.github.com/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise) +- [ ] [Configure enterprise settings](https://docs.github.com/enterprise-cloud@latest/admin/configuring-settings) | Setting | Purpose | |---------|----------| @@ -91,7 +91,7 @@ GitHub Enterprise Cloud with Data Residency requires Managed Users. ### Provider setup - [ ] Configure identity provider integration: - - **[Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-cloud-enterprise-account-tutorial)** + - **[Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-cloud-enterprise-account-tutorial)** - **SCIM provisioning** for automated user management - **Team synchronization** to map IdP groups to GitHub teams @@ -178,7 +178,7 @@ This will help you understand how to properly structure teams and permissions ba - [ ] Configure team membership management based on your authentication strategy: - **For organizations with SAML SSO**: - - Set up [team synchronization](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise) to map IdP groups to GitHub teams + - Set up [team synchronization](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise) to map IdP groups to GitHub teams - Define synchronization schedules and conflict resolution policies - **For Enterprise Managed Users**: - Use [identity provider groups](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups) to manage team memberships @@ -196,7 +196,7 @@ This will help you understand how to properly structure teams and permissions ba - Establish monitoring alerts - Test log delivery -- [ ] Configure [audit log retention](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise): +- [ ] Configure [audit log retention](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/audit-log-for-an-enterprise): - Set retention period (based on compliance requirements) - Implement backup policies - Define access controls for logs @@ -210,7 +210,7 @@ This will help you understand how to properly structure teams and permissions ba ### Policy configuration -- [ ] Configure [repository policies](https://docs.github.com/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise): +- [ ] Configure [repository policies](https://docs.github.com/enterprise-cloud@latest/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise): - Visibility settings (private, internal, public) - Fork policies - Issue creation and management @@ -266,7 +266,7 @@ This will help you understand how to properly structure teams and permissions ba ### Actions and workflow configuration {{< callout type="info" >}} -Without enabling GitHub Actions, functionality like [GitHub Copilot Coding Agent](https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot) cannot work. +Without enabling GitHub Actions, functionality like [Copilot cloud agent](https://docs.github.com/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/about-cloud-agent) cannot work. {{< /callout >}} - [ ] Set up Actions environments: @@ -275,7 +275,7 @@ Without enabling GitHub Actions, functionality like [GitHub Copilot Coding Agent - Required reviewers - Deployment gates -- [ ] Consider creating Actions [reusable workflows](https://docs.github.com/actions/how-tos/sharing-automations/reusing-workflows): +- [ ] Consider creating Actions [reusable workflows](https://docs.github.com/actions/how-tos/reuse-automations/reuse-workflows): - CI build workflows - Test automation workflows - Release automation workflows @@ -314,5 +314,5 @@ Without enabling GitHub Actions, functionality like [GitHub Copilot Coding Agent After completing your target environment setup: -1. Review the [GitHub Well-Architected Framework Security Pillar](https://wellarchitected.github.com/pillars/security/) +1. Review the [GitHub Well-Architected Framework Security Pillar](https://learn.github.com/well-architected/library/application-security/) 2. Proceed to [Migration Testing](./test) diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/04-migration-testing.md b/content/library/scenarios/migrations/azure-devops-migration-guide/04-migration-testing.md index ee83e40..784da0e 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/04-migration-testing.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/04-migration-testing.md @@ -41,12 +41,8 @@ Use this checklist to help guide your migration testing: Before you begin, review these resources to support your migration testing: -- **GitHub documentation** - - [Performing a test migration](https://docs.github.com/migrations/using-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/performing-a-test-migration-with-github-enterprise-importer) - - [Troubleshooting migrations](https://docs.github.com/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer) -- **Well-Architected Framework** - - [Testing strategy](https://wellarchitected.github.com/reliability/testing/) - - [Risk management](https://wellarchitected.github.com/reliability/risk-mitigation/) +- [Performing a dry run migration for every repository](https://docs.github.com/migrations/overview/planning-your-migration-to-github#performing-a-dry-run-migration-for-every-repository) +- [Troubleshooting migrations](https://docs.github.com/migrations/troubleshooting/troubleshooting-your-migration-with-github-enterprise-importer) ## Test environment setup @@ -133,7 +129,7 @@ gh extension install github/gh-gei - Organization member management - Workflow management access - [ ] Run basic commands -- [ ] Review the [limitations of GitHub Enterprise Importer](https://docs.github.com/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud#limitations-on-migrated-data) to understand what data will be migrated +- [ ] Review the [limitations of GitHub Enterprise Importer](https://docs.github.com/migrations/ado/understand-migrations-from-azure-devops-to-github#limitations-on-migrated-data) to understand what data will be migrated ### 2. Additional tools diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/05-repository-migration.md b/content/library/scenarios/migrations/azure-devops-migration-guide/05-repository-migration.md index 14928f2..f79b5aa 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/05-repository-migration.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/05-repository-migration.md @@ -37,10 +37,9 @@ Use this checklist to help guide your migration: Before you begin, review these migration-specific resources to support your work: -- **GitHub documentation** - - [Migrating repositories with GitHub Enterprise Importer](https://docs.github.com/migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer) - - [Reclaiming mannequins](https://docs.github.com/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer) - - [Troubleshooting your migration](https://docs.github.com/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer) +- [Migrate your repositories from Azure DevOps to GitHub](https://docs.github.com/migrations/ado/migrate-your-repositories-from-azure-devops-to-github) +- [Reclaiming mannequins](https://docs.github.com/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer) +- [Troubleshooting your migration](https://docs.github.com/migrations/troubleshooting/troubleshooting-your-migration-with-github-enterprise-importer) ## Pre-migration checklist @@ -50,12 +49,12 @@ Before you begin, review these migration-specific resources to support your work | Component | Purpose | Status | |-----------|---------|---------| - | [Authentication](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management) | Immediate user access | | + | [Authentication](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam) | Immediate user access | | | [Teams and permissions](https://docs.github.com/organizations/organizing-members-into-teams/about-teams) | Prevent access issues | | | [Repository policies](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | Security compliance | | - | [Integration settings](https://docs.github.com/enterprise-cloud@latest/get-started/exploring-integrations/about-using-integrations) | Service continuity | | + | [Integration settings](https://docs.github.com/enterprise-cloud@latest/integrations/concepts/about-integrations) | Service continuity | | | [Repository rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | Code integrity | | - | [Audit logging](https://docs.github.com/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise) | Compliance tracking | | + | [Audit logging](https://docs.github.com/enterprise-cloud@latest/admin/concepts/security-and-compliance/audit-log-for-an-enterprise) | Compliance tracking | | - [ ] Perform environment validation tests: - Confirm user access and permissions using test accounts @@ -129,7 +128,7 @@ Before you begin, review these migration-specific resources to support your work ### Repository migration -Execute the migration using GitHub Enterprise Importer. For complete instructions, see [Migrating repositories from Azure DevOps to GitHub Enterprise Cloud](https://docs.github.com/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud). +Execute the migration using GitHub Enterprise Importer. For complete instructions, see [Migrating repositories from Azure DevOps to GitHub Enterprise Cloud](https://docs.github.com/migrations/ado/migrate-your-repositories-from-azure-devops-to-github). ```bash # Basic migration command (all parameters are required) @@ -270,7 +269,7 @@ After successful migration, you'll need to map migrated users (represented by ma - Set up pull request validation pipelines - Update environment deployment approvals -- [ ] Set up build triggers for [GitHub events](https://docs.github.com/actions/reference/events-that-trigger-workflows) +- [ ] Set up build triggers for [GitHub events](https://docs.github.com/actions/reference/workflows-and-actions/events-that-trigger-workflows) - Configure branch and path filters as needed - Define additional triggers based on your workflow requirements diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/06-post-migration.md b/content/library/scenarios/migrations/azure-devops-migration-guide/06-post-migration.md index 7c40a08..f636dbd 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/06-post-migration.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/06-post-migration.md @@ -38,11 +38,11 @@ Before you begin, review these post-migration resources to support your work: - **GitHub documentation** - [About GitHub Enterprise Cloud](https://docs.github.com/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud) - - [Governance and policy recommendations](https://wellarchitected.github.com/library/governance/recommendations/governance-policies-best-practices/) - **Well-Architected Framework** - - [Governance Checklist](https://wellarchitected.github.com/library/governance/checklist/) - - [Security Best Practices](https://wellarchitected.github.com/library/application-security/recommendations/actions-security/) - - [Repository Rulesets](https://wellarchitected.github.com/library/governance/recommendations/rulesets-best-practices/) + - [Governance and policy recommendations](https://learn.github.com/well-architected/library/governance/recommendations/governance-policies-best-practices/) + - [Governance Checklist](https://learn.github.com/well-architected/library/governance/checklist/) + - [Security Best Practices](https://learn.github.com/well-architected/library/application-security/recommendations/actions-security/) + - [Repository Rulesets](https://learn.github.com/well-architected/library/governance/recommendations/managing-repositories-at-scale/rulesets-best-practices/) ## Repository governance diff --git a/content/library/scenarios/migrations/azure-devops-migration-guide/overview.md b/content/library/scenarios/migrations/azure-devops-migration-guide/overview.md index 4b58e7f..3a2e68e 100644 --- a/content/library/scenarios/migrations/azure-devops-migration-guide/overview.md +++ b/content/library/scenarios/migrations/azure-devops-migration-guide/overview.md @@ -84,7 +84,7 @@ Before you begin, review these essential resources: | [GitHub Enterprise Cloud documentation](https://docs.github.com/enterprise-cloud@latest) | Platform documentation | | [GitHub Enterprise Importer](https://docs.github.com/migrations/using-github-enterprise-importer) | Migration tool guide | | [Azure DevOps Integration](https://learn.microsoft.com/en-us/azure/devops/cross-service/github-integration) | Integration options | -| [Well-Architected Framework](https://wellarchitected.github.com/) | Best practices | +| [Well-Architected Framework](https://learn.github.com/well-architected/) | Best practices | ## Seeking further assistance @@ -113,7 +113,7 @@ GEI is recommended for most migrations. | Automation | _Supports interactive and scripted migrations_ | | Reliability | _Provides error handling and retry mechanisms_ | -> Review [GEI limitations on migrated data.](https://docs.github.com/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud#limitations-on-migrated-data) +> Review [GEI limitations on migrated data.](https://docs.github.com/migrations/ado/understand-migrations-from-azure-devops-to-github#limitations-on-migrated-data) #### Git-based Migration @@ -174,17 +174,17 @@ Understanding the current environment is fundamental for a successful migration. - Document the current permissions and access patterns of repositories. - Document all integrations and external tools in use. - Document current usage patterns and workflows for transition planning. -- [Design plans for policy and governance of the target environment](https://wellarchitected.github.com/library/governance/checklist/). +- [Design plans for policy and governance of the target environment](https://learn.github.com/well-architected/library/governance/checklist/). ### Target Environment Design and Configuration Find additional guidance in the [Target Environment Setup guide](./setup). -Making sure that the target GitHub Enterprise Cloud environment is set up for success is critical for a successful migration process. Learn more about GitHub Enterprise Administration and Governance on [GitHub Resources](https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/) and [GitHub Well Architected](https://wellarchitected.github.com/). +Making sure that the target GitHub Enterprise Cloud environment is set up for success is critical for a successful migration process. Learn more about GitHub Enterprise Administration and Governance on [Essentials of governance and administration with GitHub Enterprise](https://learn.github.com/well-architected/library/governance/recommendations/governance-administration-essentials/) and [GitHub Well Architected](https://learn.github.com/well-architected/). - Administrators should plan for learning about GitHub Enterprise Cloud and its features. - [Microsoft Learn](https://learn.microsoft.com/en-us/training/paths/github-administration-products/) has options available for self-paced learning. -- Map source environment repository structures to [target organizations/repositories](https://docs.github.com/migrations/overview/planning-your-migration-to-github#designing-your-organization-structure-for-the-migration-destination). +- Map source environment repository structures to [target organizations/repositories](https://docs.github.com/migrations/overview/planning-your-migration-to-github#defining-your-origin-and-destination). - Plan the structure of the target environment. - Plan for handling large files and repositories. - Plan for handling release tags and release artifacts. diff --git a/content/library/scenarios/migrations/repository-checklist.md b/content/library/scenarios/migrations/repository-checklist.md index 36b396b..0516f61 100644 --- a/content/library/scenarios/migrations/repository-checklist.md +++ b/content/library/scenarios/migrations/repository-checklist.md @@ -20,11 +20,11 @@ This checklist is intended to facilitate a successful migration to GitHub by pro ## Migration Tools -For a detailed reference based on source and destination environments, see [Migration tools comparison on GitHub Docs](https://docs.github.com/en/enterprise-cloud@latest/migrations/overview/migration-paths-to-github). +For a detailed reference based on source and destination environments, see [Migration tools comparison on GitHub Docs](https://docs.github.com/enterprise-cloud@latest/migrations/overview/migration-paths-to-github). -- [**GitHub Enterprise Importer**](https://docs.github.com/en/enterprise-cloud@latest/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer): Recommended for migrations to GitHub.com and GitHub Enterprise Cloud, allows for migrations of source repository content along with associated metadata, such as Pull Requests and Issues. - - **Important**: Learn about [limitations of GitHub Enterprise Importer on GitHub Docs](https://docs.github.com/en/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products#limitations-of-github-enterprise-importer) to plan for additional considerations for your migration. -- [**ghe-migrator**](https://docs.github.com/en/enterprise-cloud@latest/migrations/using-ghe-migrator/about-ghe-migrator): Recommended for migrations to GitHub Enterprise Server, allows for migrations of source repository content along with associated metadata. +- [**GitHub Enterprise Importer**](https://docs.github.com/enterprise-cloud@latest/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer): Recommended for migrations to GitHub.com and GitHub Enterprise Cloud, allows for migrations of source repository content along with associated metadata, such as Pull Requests and Issues. + - **Important**: Learn about [limitations of GitHub Enterprise Importer on GitHub Docs](https://docs.github.com/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products#limitations-of-github-enterprise-importer) to plan for additional considerations for your migration. +- [**ghe-migrator**](https://docs.github.com/enterprise-cloud@latest/migrations/using-ghe-migrator/about-ghe-migrator): Recommended for migrations to GitHub Enterprise Server, allows for migrations of source repository content along with associated metadata. - **Git-based migration**: For source-only repository content migrations without metadata. ## Project Planning @@ -49,23 +49,23 @@ Understanding the current environment is fundamental for a successful migration. - Document the current organizational and team structure. - Document inventory structure to applications and services. - Document dependencies for repositories. -- [Assess and document existing repository data like sizes, commit history, submodule usage, and Git LFS usage.](https://docs.github.com/en/migrations/overview/planning-your-migration-to-github#building-a-basic-inventory-of-the-repositories-you-want-to-migrate) +- [Assess and document existing repository data like sizes, commit history, submodule usage, and Git LFS usage.](https://docs.github.com/migrations/overview/planning-your-migration-to-github#building-a-basic-inventory-of-the-repositories-you-want-to-migrate) - Document branch policies to recreate in the target environment. - Document the current permissions and access patterns of repositories. - Document all integrations and external tools in use. - Identify the need for reverse proxy or app gateway strategy to consume webhook and audit log data. - Document current usage patterns and workflows for transition planning. -- [Design plans for policy and governance of the target environment](https://wellarchitected.github.com/library/governance/checklist/). +- [Design plans for policy and governance of the target environment](https://learn.github.com/well-architected/library/governance/checklist/). ## Target Environment Design and Configuration -Making sure that the target GitHub Enterprise Cloud environment is set up for success is critical for a successful migration process. Learn more about GitHub Enterprise Administration and Governance on [GitHub Resources](https://resources.github.com/learn/pathways/administration-governance/essentials/administration-governance-github-enterprise-cloud/) and [Governance Design Principles](https://wellarchitected.github.com/library/governance/design-principles/). +Making sure that the target GitHub Enterprise Cloud environment is set up for success is critical for a successful migration process. Learn more about GitHub Enterprise Administration and Governance on [Essentials of governance and administration with GitHub Enterprise](https://learn.github.com/well-architected/library/governance/recommendations/governance-administration-essentials/) and [Governance Design Principles](https://learn.github.com/well-architected/library/governance/design-principles/). -- Map source environment repository structures to [target organizations/repositories](https://docs.github.com/en/migrations/overview/planning-your-migration-to-github#designing-your-organization-structure-for-the-migration-destination). +- Map source environment repository structures to [target organizations/repositories](https://docs.github.com/migrations/overview/planning-your-migration-to-github#defining-your-origin-and-destination). - Plan the structure of the target environment. - Plan for handling large files and repositories. - Plan for handling release tags and release artifacts. -- Set up identity access in the target environment. See [Identity and access management](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises) for more information on Enterprise identity management configuration options. +- Set up identity access in the target environment. See [Identity and access management](https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises) for more information on Enterprise identity management configuration options. - Configure enterprise, organization, and team structure. - Configure governance and policy settings. - Conduct security assessments on the target environment. @@ -79,7 +79,7 @@ Thorough testing and preparation are essential for successful migrations, as the - [Choose migration tools](#migration-tools). - Prepare any dependencies for migration tools, as required, such as infrastructure needs, firewall/network configurations, and authentication methods. - Correct any issues on existing repository data or make plans for mitigation (such as large files, commit history, metadata sizing, submodules, and Git LFS usage) based on migration method. -- [Perform dry-run migrations to identify issues.](https://docs.github.com/en/migrations/overview/planning-your-migration-to-github#performing-a-dry-run-migration-for-every-repository) +- [Perform dry-run migrations to identify issues.](https://docs.github.com/migrations/overview/planning-your-migration-to-github#performing-a-dry-run-migration-for-every-repository) - Identify integration and external tools compatibility issues. - Configure reverse proxy or app gateway as needed for integration of webhooks and audit log data. - Run pilot migrations, document and address issues. @@ -99,7 +99,7 @@ Executing the migration is a critical phase that requires coordination and monit - Create a dedicated migration support channel for issue resolution - Execute the migration plan runbook. - Track migration status and fix errors. -- [Link identity attribution](https://docs.github.com/en/enterprise-cloud@latest/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer) (when using GitHub Enterprise Importer). +- [Link identity attribution](https://docs.github.com/enterprise-cloud@latest/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer) (when using GitHub Enterprise Importer). ## Post-Migration Activities diff --git a/content/library/scenarios/nist-ssdf-implementation.md b/content/library/scenarios/nist-ssdf-implementation.md index 19ca6a8..879ac9c 100644 --- a/content/library/scenarios/nist-ssdf-implementation.md +++ b/content/library/scenarios/nist-ssdf-implementation.md @@ -94,7 +94,7 @@ The full NIST SSDF v1.1 specification is available at: }} -For more detailed guidance per alert type, refer to [Prioritizing Security Alert Remediation](https://wellarchitected.github.com/library/application-security/recommendations/prioritizing-alerts/). +For more detailed guidance per alert type, refer to [Prioritizing Security Alert Remediation](https://learn.github.com/well-architected/library/application-security/recommendations/prioritizing-alerts/). {{< /callout >}} #### RV.3: Analyze vulnerabilities to identify their root causes