Secure use reference

Find information about security best practices when you are writing workflows and using GitHub Actions security features.

Writing workflows

Use secrets for sensitive information

Because there are multiple ways a secret value can be transformed, automatic redaction is not guaranteed. Adhere to the following best practices to limit risks associated with secrets.

• Principal of least privilege
  • Any user with write access to your repository has read access to all secrets configured in your repository. Therefore, you should ensure that the credentials being used within workflows have the least privileges required.
  • Actions can use the GITHUB_TOKEN by accessing it from the github.token context. For more information, see Contexts reference. You should therefore make sure that the GITHUB_TOKEN is granted the minimum required permissions. It's good security practice to set the default permission for the GITHUB_TOKEN to read access only for repository contents. The permissions can then be increased, as required, for individual jobs within the workflow file. For more information, see Use GITHUB_TOKEN in workflows.
• Mask sensitive data
  • Sensitive data should never be stored as plaintext in workflow files. Mask all sensitive information that is not a GitHub secret by using ::add-mask::VALUE. This causes the value to be treated as a secret and redacted from logs. For more information about masking data, see GitHub Actions에 대한 워크플로 명령.
• Delete and rotate exposed secrets
  • Redacting of secrets is performed by your workflow runners. This means a secret will only be redacted if it was used within a job and is accessible by the runner. If an unredacted secret is sent to a workflow run log, you should delete the log and rotate the secret. For information on deleting logs, see 워크플로 실행 로그 사용.
• Never use structured data as a secret
  • Structured data can cause secret redaction within logs to fail, because redaction largely relies on finding an exact match for the specific secret value. For example, do not use a blob of JSON, XML, or YAML (or similar) to encapsulate a secret value, as this significantly reduces the probability the secrets will be properly redacted. Instead, create individual secrets for each sensitive value.
• Register all secrets used within workflows
  • If a secret is used to generate another sensitive value within a workflow, that generated value should be formally registered as a secret, so that it will be redacted if it ever appears in the logs. For example, if using a private key to generate a signed JWT to access a web API, be sure to register that JWT as a secret or else it won’t be redacted if it ever enters the log output.
  • Registering secrets applies to any sort of transformation/encoding as well. If your secret is transformed in some way (such as Base64 or URL-encoded), be sure to register the new value as a secret too.
• Audit how secrets are handled
  • Audit how secrets are used, to help ensure they’re being handled as expected. You can do this by reviewing the source code of the repository executing the workflow, and checking any actions used in the workflow. For example, check that they’re not sent to unintended hosts, or explicitly being printed to log output.
  • View the run logs for your workflow after testing valid/invalid inputs, and check that secrets are properly redacted, or not shown. It's not always obvious how a command or tool you’re invoking will send errors to STDOUT and STDERR, and secrets might subsequently end up in error logs. As a result, it is good practice to manually review the workflow logs after testing valid and invalid inputs. For information on how to clean up workflow logs that may unintentionally contain sensitive data, see 워크플로 실행 로그 사용.
• Audit and rotate registered secrets
  • Periodically review the registered secrets to confirm they are still required. Remove those that are no longer needed.
  • Rotate secrets periodically to reduce the window of time during which a compromised secret is valid.
• Consider requiring review for access to secrets
  • You can use required reviewers to protect environment secrets. A workflow job cannot access environment secrets until approval is granted by a reviewer. For more information about storing secrets in environments or requiring reviews for environments, see Using secrets in GitHub Actions and 배포 환경 관리.

Good practices for mitigating script injection attacks

Recommended approaches for mitigating the risk of script injection in your workflows:

Use an action instead of an inline script

The recommended approach is to create a JavaScript action that processes the context value as an argument. This approach is not vulnerable to the injection attack, since the context value is not used to generate a shell script, but is instead passed to the action as an argument:

uses: fakeaction/checktitle@v3
with:
  title: ${{ github.event.pull_request.title }}

Use an intermediate environment variable

For inline scripts, the preferred approach to handling untrusted input is to set the value of the expression to an intermediate environment variable. The following example uses Bash to process the github.event.pull_request.title value as an environment variable:

      - name: Check PR title
        env:
          TITLE: ${{ github.event.pull_request.title }}
        run: |
          if [[ "$TITLE" =~ ^octocat ]]; then
          echo "PR title starts with 'octocat'"
          exit 0
          else
          echo "PR title did not start with 'octocat'"
          exit 1
          fi

In this example, the attempted script injection is unsuccessful, which is reflected by the following lines in the log:

   env:
     TITLE: a"; ls $GITHUB_WORKSPACE"
PR title did not start with 'octocat'

With this approach, the value of the ${{ github.event.pull_request.title }} expression is stored in memory and used as a variable, and doesn't interact with the script generation process. In addition, consider using double quote shell variables to avoid word splitting, but this is one of many general recommendations for writing shell scripts, and is not specific to GitHub Actions.

Using workflow templates for code scanning

Code scanning allows you to find security vulnerabilities before they reach production. GitHub provides workflow templates for code scanning. You can use these suggested workflows to construct your code scanning workflows, instead of starting from scratch. GitHub's workflow, the CodeQL 분석 워크플로, is powered by CodeQL. There are also third-party workflow templates available.

For more information, see 코드 검사 정보 and 코드 스캔을 위한 고급 설정 구성.

Restricting permissions for tokens

To help mitigate the risk of an exposed token, consider restricting the assigned permissions. For more information, see Use GITHUB_TOKEN in workflows.

Using third-party actions

The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them.

This means that a compromise of a single action within a workflow can be very significant, as that compromised action would have access to all secrets configured on your repository, and may be able to use the GITHUB_TOKEN to write to the repository. Consequently, there is significant risk in sourcing actions from third-party repositories on GitHub. For information on some of the steps an attacker could take, see Secure use reference.

You can help mitigate this risk by following these good practices:

• Pin actions to a full length commit SHA

  Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload. SHA를 선택할 때는 해당 SHA가 리포지토리 포크가 아닌 작업의 리포지토리에서 온 것인지 확인해야 합니다.

• Audit the source code of the action

  Ensure that the action is handling the content of your repository and secrets as expected. For example, check that secrets are not sent to unintended hosts, or are not inadvertently logged.

• Pin actions to a tag only if you trust the creator

  Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on GitHub Marketplace is a useful signal, as it indicates that the action was written by a team whose identity has been verified by GitHub. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action.

Reusing third-party workflows

The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see Reuse workflows.

GitHub's security features

GitHub provides many features to make your code more secure. You can use GitHub's built-in features to understand the actions your workflows depend on, ensure you are notified about vulnerabilities in the actions you consume, or automate the process of keeping the actions in your workflows up to date. If you publish and maintain actions, you can use GitHub to communicate with your community about vulnerabilities and how to fix them. For more information about security features that GitHub offers, see GitHub security features(GitHub 보안 기능).

Using CODEOWNERS to monitor changes

You can use the CODEOWNERS feature to control how changes are made to your workflow files. For example, if all your workflow files are stored .github/workflows, you can add this directory to the code owners list, so that any proposed changes to these files will first require approval from a designated reviewer.

For more information, see 코드 소유자 정보.

Managing permissions for GitHub Actions settings in your organization

You can practice the principle of least privilege for your organization's CI/CD pipeline with GitHub Actions by administering custom organization roles. A custom organization role is a way to grant an individual or team in your organization the ability to control certain subsets of settings without granting full administrative control of the organization and its repositories.

GitHub Actions의 경우 조직의 개인 또는 팀에 대해 다음 사용 권한을 사용하도록 설정할 수 있습니다.

• 조직 Actions 정책 관리: 자체 호스트형 실행기 설정을 제외한 "Actions 일반" 설정 페이지에서 모든 설정을 관리할 수 있는 액세스 권한.
• 조직 실행기 및 실행기 그룹 관리: GitHub 호스트형 실행기, 자체 호스트형 실행기, 실행기 그룹을 만들고 관리할 수 있으며 자체 호스트형 실행기를 만들 수 있는 위치를 제어할 수 있는 액세스 권한.
• 조직 Actions 비밀 관리: Actions 조직 비밀을 만들고 관리할 수 있는 액세스 권한.
• 조직 Actions 변수 관리: Actions 조직 변수를 만들고 관리할 수 있는 액세스 권한.

For more information, see 사용자 지정 조직 역할 소개.

Using OpenID Connect to access cloud resources

GitHub Actions 워크플로가 OIDC(OpenID Connect)를 지원하는 클라우드 공급자의 리소스에 액세스해야 하는 경우 클라우드 공급자에게 직접 인증하도록 워크플로를 구성할 수 있습니다. 이렇게 하면 이러한 자격 증명을 수명이 긴 비밀로 저장하지 않을 수 있고 다른 보안 이점을 제공할 수 있습니다. 자세한 내용은 OpenID Connect을(를) 참조하세요.

Using Dependabot version updates to keep actions up to date

Dependabot를 사용하여 작업 및 리포지토리에 사용된 재사용 가능한 워크플로에 대한 참조를 최신 상태로 유지할 수 있습니다. 작업은 버그 수정 및 새로운 기능으로 수시로 업데이트되어 자동화된 프로세스의 속도, 안전, 신뢰성을 향상합니다. Dependabot는 자동으로 종속성을 유지 관리하는 작업을 수행하여 드는 노력을 줄여줍니다. 자세한 내용은 Dependabot을 사용하여 작업을 최신 상태로 유지 및 Dependabot 보안 업데이트 정보을(를) 참조하세요.

Allowing workflows to access internal and private repositories

프라이빗 리포지토리를 다른 리포지토리의 GitHub Actions 워크플로에 액세스할 수 있도록 하는 경우 다른 리포지토리의 외부 협력자는 프라이빗 리포지토리에 직접 액세스할 수 없더라도 프라이빗 리포지토리에 간접적으로 액세스할 수 있습니다. 외부 협력자는 프라이빗 리포지토리의 작업 또는 워크플로를 사용할 때 워크플로 실행에 대한 로그를 볼 수 있습니다. For more information, see 엔터프라이즈와 작업 및 워크플로 공유.

GitHub은(는) 범위가 지정된 설치 토큰을 실행기에 전달하여 작업을 다운로드할 수 있도록 합니다. 설치 토큰은 리포지토리에 대한 읽기 액세스 권한을 가지며 1시간 후에 자동으로 만료됩니다.

Preventing GitHub Actions from creating or approving pull requests

GitHub Actions 워크플로가 끌어오기 요청을 만들거나 승인하는 것을 허용하거나 차단하도록 선택할 수 있습니다. Allowing workflows, or any other automation, to create or approve pull requests could be a security risk if the pull request is merged without proper oversight.

For more information on how to configure this setting, see 엔터프라이즈에서 GitHub Actions에 대한 정책 적용, Disabling or limiting GitHub Actions for your organization, and 리포지토리에 대한 GitHub Actions 설정 관리.

Using code scanning to secure workflows

Code scanning can automatically detect and suggest improvements for common vulnerable patterns used in GitHub Actions workflows. For more information on how to enable code scanning, see 코드 스캔을 위한 기본 설정 구성.

Using OpenSSF Scorecards to secure workflow dependencies

Scorecards is an automated security tool that flags risky supply chain practices. You can use the Scorecards action and workflow template to follow best security practices. Once configured, the Scorecards action runs automatically on repository changes, and alerts developers about risky supply chain practices using the built-in code scanning experience. The Scorecards project runs a number of checks, including script injection attacks, token permissions, and pinned actions.

Hardening for GitHub-hosted runners

GitHub-hosted runners take measures to help you mitigate security risks.

Reviewing the supply chain for GitHub-hosted runners

For GitHub-hosted runners created from images maintained by GitHub, you can view a software bill of materials (SBOM) to see what software was pre-installed on the runner. You can provide your users with the SBOM which they can run through a vulnerability scanner to validate if there are any vulnerabilities in the product. If you are building artifacts, you can include this SBOM in your bill of materials for a comprehensive list of everything that went into creating your software.

SBOMs are available for Ubuntu, Windows, and macOS runner images maintained by GitHub. You can locate the SBOM for your build in the release assets at https://github.com/actions/runner-images/releases. An SBOM with a filename in the format of sbom.IMAGE-NAME.json.zip can be found in the attachments of each release.

For third-party images, such as the images for ARM-powered runners, you can find details of the software that's included in the image in the actions/partner-runner-images repository.

Denying access to hosts

GitHub호스트형 실행기는 다양한 암호 화폐 마이닝 풀 및 악성 사이트에 대한 네트워크 액세스를 차단하는 etc/hosts 파일로 프로비전됩니다. MiningMadness.com 및 cpu-pool.com 같은 호스트는 심각한 보안 위험을 초래하지 않도록 localhost로 다시 지정됩니다. For more information, see About GitHub-hosted runners.

Hardening for self-hosted runners

GitHub-hosted runners execute code within ephemeral and clean isolated virtual machines, meaning there is no way to persistently compromise this environment, or otherwise gain access to more information than was placed in this environment during the bootstrap process.

Self-hosted runners for GitHub do not have guarantees around running in ephemeral clean virtual machines, and can be persistently compromised by untrusted code in a workflow.

As a result, self-hosted runners should almost never be used for public repositories on GitHub, because any user can open pull requests against the repository and compromise the environment. Similarly, be cautious when using self-hosted runners on private or internal repositories, as anyone who can fork the repository and open a pull request (generally those with read access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the GITHUB_TOKEN which, depending on its settings, can grant write access to the repository. Although workflows can control access to environment secrets by using environments and required reviews, these workflows are not run in an isolated environment and are still susceptible to the same risks when run on a self-hosted runner.

엔터프라이즈 소유자 및 조직 소유자는 리포지토리 수준의 자체 호스트형 실행기를 만들 수 있는 리포지토리를 선택할 수 있습니다. "조직 실행기 및 실행기 그룹 관리" 권한을 가진 사용자는 조직의 리포지토리에 대해 리포지토리 수준의 자체 호스트형 실행기를 만들 수 있는 리포지토리만 선택할 수 있습니다.

사용자 지정 조직 역할에 대한 자세한 내용은 사용자 지정 조직 역할 소개을(를) 참조하세요.

자세한 내용은 엔터프라이즈에서 GitHub Actions에 대한 정책 적용 및 조직의 GitHub Actions 사용 안 함 또는 제한을(를) 참조하세요.

When a self-hosted runner is defined at the organization or enterprise level, GitHub can schedule workflows from multiple repositories onto the same runner. Consequently, a security compromise of these environments can result in a wide impact. To help reduce the scope of a compromise, you can create boundaries by organizing your self-hosted runners into separate groups. You can restrict what workflows, organizations and repositories can access runner groups. For more information, see 그룹을 사용하여 자체 호스트형 실행기에 대한 액세스 관리.

You should also consider the environment of the self-hosted runner machines:

• What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others.
• Does the machine have network access to sensitive services? For example, Azure or AWS metadata services. The amount of sensitive information in this environment should be kept to a minimum, and you should always be mindful that any user capable of invoking workflows has access to this environment.

Some customers might attempt to partially mitigate these risks by implementing systems that automatically destroy the self-hosted runner after each job execution. However, this approach might not be as effective as intended, as there is no way to guarantee that a self-hosted runner only runs one job. Some jobs will use secrets as command-line arguments which can be seen by another job running on the same runner, such as ps x -w. This can lead to secret leaks.

Using just-in-time runners

To improve runner registration security, you can use the REST API to create ephemeral, just-in-time (JIT) runners. These self-hosted runners perform at most one job before being automatically removed from the repository, organization, or enterprise. For more information about configuring JIT runners, see 자체 호스트형 실행기에 대한 REST API 엔드포인트.

Once you have the config file from the REST API response, you can pass it to the runner at startup.

./run.sh --jitconfig ${encoded_jit_config}

Planning your management strategy for self-hosted runners

A self-hosted runner can be added to various levels in your GitHub hierarchy: the enterprise, organization, or repository level. This placement determines who will be able to manage the runner:

Centralized management:

• If you plan to have a centralized team own the self-hosted runners, then the recommendation is to add your runners at the highest mutual organization or enterprise level. This gives your team a single location to view and manage your runners.
• If you only have a single organization, then adding your runners at the organization level is effectively the same approach, but you might encounter difficulties if you add another organization in the future.

Decentralized management:

• If each team will manage their own self-hosted runners, then the recommendation is to add the runners at the highest level of team ownership. For example, if each team owns their own organization, then it will be simplest if the runners are added at the organization level too.
• You could also add runners at the repository level, but this will add management overhead and also increases the numbers of runners you need, since you cannot share runners between repositories.

Authenticating to your cloud provider

If you are using GitHub Actions to deploy to a cloud provider, or intend to use HashiCorp Vault for secret management, then it's recommended that you consider using OpenID Connect to create short-lived, well-scoped access tokens for your workflow runs. For more information, see OpenID Connect.

Auditing GitHub Actions events

You can use the security log to monitor activity for your user account and the audit log to monitor activity in your organization or enterprise. The security and audit log records the type of action, when it was run, and which personal account performed the action.

For example, you can use the audit log to track the org.update_actions_secret event, which tracks changes to organization secrets.

For the full list of events that you can find in the audit log for each account type, see the following articles:

• 보안 로그 이벤트
• 조직의 감사 로그 이벤트
• 엔터프라이즈에 대한 감사 로그 이벤트

Understanding dependencies in your workflows

You can use the dependency graph to explore the actions that the workflows in your repository use. The dependency graph is a summary of the manifest and lock files stored in a repository. It also recognizes files in ./github/workflows/ as manifests, which means that any actions or workflows referenced using the syntax jobs[*].steps[*].uses or jobs.<job_id>.uses will be parsed as dependencies.

The dependency graph shows the following information about actions used in workflows:

• The account or organization that owns the action.
• The workflow file that references the action.
• The version or SHA the action is pinned to.

In the dependency graph, dependencies are automatically sorted by vulnerability severity. If any of the actions you use have security advisories, they will display at the top of the list. You can navigate to the advisory from the dependency graph and access instructions for resolving the vulnerability.

The dependency graph is enabled for public repositories, and you can choose to enable it on private repositories. For more information about using the dependency graph, see 리포지토리의 종속성 탐색.

Being aware of security vulnerabilities in actions you use

For actions available on the marketplace, GitHub reviews related security advisories and then adds those advisories to the GitHub Advisory Database. You can search the database for actions that you use to find information about existing vulnerabilities and instructions for how to fix them. To streamline your search, use the GitHub Actions filter in the GitHub Advisory Database.

You can set up your repositories so that you:

• Receive alerts when actions used in your workflows receive a vulnerability report. For more information, see Monitoring the actions in your workflows.
• Are warned about existing advisories when you add or update an action in a workflow. For more information, see Screening actions for vulnerabilities in new or updated workflows.

Monitoring the actions in your workflows

You can use Dependabot to monitor the actions in your workflows and enable Dependabot alerts to notify you when an action you use has a reported vulnerability. Dependabot performs a scan of the default branch of the repositories where it is enabled to detect insecure dependencies. Dependabot generates Dependabot alerts when a new advisory is added to the GitHub Advisory Database or when an action you use is updated.

You can enable Dependabot alerts for your personal account, for a repository, or for an organization. For more information, see Dependabot 경고 구성.

리포지토리의 Dependabot alerts 탭에서 열려 있거나 닫혀 있는 모든 Dependabot alerts 및 해당 Dependabot security updates을(를) 볼 수 있습니다. For more information, see Dependabot 경고 보기 및 업데이트.

Screening actions for vulnerabilities in new or updated workflows

When you open pull requests to update your workflows, it is good practice to use dependency review to understand the security impact of changes you've made to the actions you use. 종속성 검토는 모든 끌어오기 요청에서 종속성 변경 내용과 이러한 변경 내용의 보안 영향을 이해하는 데 도움이 됩니다. 끌어오기 요청의 “변경된 파일” 탭에서 서식 있는 Diff로 종속성 변경 내용을 쉽게 이해할 수 있습니다. 종속성 검토는 다음을 알려줍니다.

• 릴리스 날짜와 함께 추가, 제거 또는 업데이트된 종속성
• 이러한 구성 요소를 사용하는 프로젝트 수
• 이러한 종속성에 대한 취약성 데이터

If any of the changes you made to your workflows are flagged as vulnerable, you can avoid adding them to your project or update them to a secure version.

For more information about dependency review, see 종속성 검토 정보.

"종속성 검토 작업"은 GitHub Actions 컨텍스트 내에서 끌어오기 요청의 차이점을 보고할 수 있는 특정 작업을 나타냅니다. dependency-review-action을 참조하세요. 리포지토리에서 을(를) 사용하여 끌어오기 요청에 대한 종속성 검토를 적용할 수 있습니다. 이 작업은 끌어오기 요청의 패키지 버전 변경에 의해 도입된 취약한 종속성 버전을 검사하고 관련 보안 취약성에 대해 경고합니다. 이를 통해 끌어오기 요청의 변경 내용을 보다 잘 파악할 수 있으며 취약성이 리포지토리에 추가되지 않도록 방지할 수 있습니다. For more information, see 종속성 검토 정보.

Keeping the actions in your workflows secure and up to date

Dependabot를 사용하여 작업 및 리포지토리에 사용된 재사용 가능한 워크플로에 대한 참조를 최신 상태로 유지할 수 있습니다. 작업은 버그 수정 및 새로운 기능으로 수시로 업데이트되어 자동화된 프로세스의 속도, 안전, 신뢰성을 향상합니다. Dependabot는 자동으로 종속성을 유지 관리하는 작업을 수행하여 드는 노력을 줄여줍니다. 자세한 내용은 Dependabot을 사용하여 작업을 최신 상태로 유지 및 Dependabot 보안 업데이트 정보을(를) 참조하세요.

The following features can automatically update the actions in your workflows.

• Dependabot version updates open pull requests to update actions to the latest version when a new version is released.
• Dependabot security updates open pull requests to update actions with reported vulnerabilities to the minimum patched version.

For information on how to configure Dependabot version updates, see Dependabot 버전 업데이트 구성.

For information on how to configure Dependabot security updates, see Dependabot 보안 업데이트 구성..

Protecting actions you've created

GitHub enables collaboration between people who publish and maintain actions and vulnerability reporters in order to promote secure coding. 리포지토리 보안 권고를 통해 퍼블릭 리포지토리 유지 관리자가 프로젝트의 보안 취약성을 비공개로 논의하고 수정할 수 있습니다. 수정 사항을 공동으로 수행한 후 리포지토리 관리자는 보안 공지를 게시하여 보안 취약성을 프로젝트 커뮤니티에 공개적으로 공개할 수 있습니다. 리포지토리 관리자는 보안 공지를 게시하여 커뮤니티가 더 쉽게 패키지 종속성을 업데이트하고 보안 취약성의 영향을 조사할 수 있습니다.

If you are someone who maintains an action that is used in other projects, you can use the following GitHub features to enhance the security of the actions you've published.

• Use the dependants view in the Dependency graph to see which projects depend on your code. If you receive a vulnerability report, this will give you an idea of who you need to communicate with about the vulnerability and how to fix it. For more information, see 리포지토리의 종속성 탐색.
• Use repository security advisories to create a security advisory, privately collaborate to fix the vulnerability in a temporary private fork, and publish a security advisory to alert your community of the vulnerability once a patch is released. For more information, see 리포지토리에 대한 프라이빗 취약성 보고 구성 and 리포지토리 보안 공지 만들기.