GitHub Actions: Accessing content from other repositories 1/2

By default, GitHub Actions only allows access to the current repository. However, there are scenarios where you need to access content from other repositories. For example, you may want to use a template repository to create a new repository, built your code by stitching together multiple repositories, Or you may want to access a repository that contains a set of scripts that you want to use in your workflow, contains a set of configuration files that you want to keep in a central place or just data files to be shared in multiple repositories.

The generic answer is to use the actions/checkout action to checkout the repository you want to access. This will place the content of the repository in the GITHUB_WORKSPACE directory, and you can then use the content as you would use any other content in your repository.

But this only works for public repositories, to access internal or private repositories you need a way to authenticate since the GITHUB_TOKEN is scoped to the current repository.

This authentication can be done using several methods:

• Personal Acess tokens Both fine grained tokens and classic can be used to clone repositories.
• GitHub App
• SSH keys
• Deploy keys

Each method has its pros and cons

Authentication methods to access a repository (that includes cloning)

Personal Access Token (fine grained)

GitHub fine-grained tokens are a type of personal access token that provide more granular control over the permissions and scope of access to GitHub resources. These tokens can be generated and managed in the GitHub account settings.

Learn more about fine grained personal access tokens in the GitHub documentation.

Pros

• Simple to use
• Simple to manage to which repositories the token has access to
  • Managed in a central place
• Can be used to access multiple organizations.
• Can also be used to call GitHub APIs
• Admins can enforce approval workflows for token use

Cons

• It is tied to a user account, if the user loses access to the repository or the account is disabled the automation will stop working
  • This can be mitigated by using a service account, which is the recommended approach. Never user personal accounts for automation.
    • Using a service account also improves auditability.
• Permission and access is easy to manage.
• You need to login to GitHub to create/rotate the token
• Token needs to be stored in a secure way
• Consumes a license

Personal Access Token (classic)

GitHub Personal Access Tokens (Classic) are a type of token that provide authentication and access to GitHub resources. These tokens can be generated and managed in the GitHub account settings.

Learn more about classic personal access tokens in the GitHub documentation.

Pros

• Simple to use
• Better control over permissions
• Is scoped to a single organization or user (unlike the Classic PAT). (this is both a pro and a con depending on the perspective)
• Can also be used to call GitHub APIs

Cons

• It is tied to a user account, if the user loses access to the repository or the account is disabled the automation will stop working
  • This can be mitigated by using a service account, which is the recommended approach. Never user personal accounts for automation.
    • Using a service account also improves auditability.
• Permission and access are hard to manage:
  • Access needs to be granted to each repository individually (teams can also be used)
    • Which means repo admin may (unknowingly) remove access to the account and break the automation
  • No single place to visualize to which repository the account has access to
• You need to login to GitHub to create/rotate the token
• Token needs to be stored in a secure way
• Consumes a license
• Is scoped to a single organization or user (unlike the Classic PAT). (this is both a pro and a con depending on the perspective)

GitHub App

GitHub Apps are a way to extend the functionality of GitHub repositories and organizations. They can be used to automate workflows, integrate with external services, and perform various tasks on behalf of users or organizations.

Unlike personal access tokens or deploy keys, GitHub Apps are not tied to a specific user account. They can be installed on multiple repositories and organizations, allowing them to access and interact with the repositories' data and settings.

GitHub Apps have their own permissions and can be granted read or write access to specific repositories. They can also make API calls to retrieve information or perform actions on GitHub.

One advantage of using GitHub Apps is that they provide better auditability and control over the actions performed by the app. They can be managed and configured within the GitHub Apps settings, allowing administrators to monitor and control the app's behavior.

Learn more about GitHub Apps in the GitHub Apps documentation.

Pros

• Can be used to access multiple organizations.
• Can also be used to call GitHub APIs

Cons

• You can only register 100 apps per organization

SSH Key

See Adding a new SSH key to your GitHub account

Pros

• Can only be used to clone repositories (this can be also seen as a con depending on the perspective)

Cons

• Cannot be used to call GitHub APIs (this can be also seen as a pro depending on the perspective)
• It is tied to a user account, if the user loses access to the repository or the account is disabled the automation will stop working
  • This can be mitigated by using a service account, which is the recommended approach. Never user personal accounts for automation.

Deploy Key

A GitHub deploy key is an SSH key that can be granted access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account. Deploy keys can be granted read or read-write access to the repository. They are commonly used for automated deployment processes, allowing external services or servers to securely access the repository without requiring personal user credentials. Deploy keys are managed within the repository settings and can be added or removed as needed.

See Managing deploy keys.

Pros

• Simple to use
• Absolute minimum permissions. Can only be used to clone or push changes to repository.
• It is not tied to an account
  • Doesn't consume a license

Cons

• Cannot be used to call GitHub APIs (this can be also seen as a pro depending on the perspective)
• The same key cannot be assigned to multiple repositories (this can be also seen as a pro depending on the perspective)
• Key needs to be stored in a secure way

Conclusion

Based on the pros and con above, the recommended approach is most of the time to use a GitHub App, you can read more about how to use GitHub Apps for service accounts on Demystifying GitHub Apps: Using GitHub Apps to Replace Service Accounts blog post, it is generic to be used in other scenarios but it has a section how to use if from GitHub Actions.

This was part 1 of this post, and it was only meant as an introduction for the next post where I will show how to use a simpler and better approach to access content from other repositories in GitHub Actions for some specific scenarios.