8.2 KiB
github-action-push-to-another-repository
This GitHub Action will help to push files that exist in a GitHub repository or that are generated by another GitHub action into a new repository.
Please read the documentation to understand which files and commits are kept in the destination repository and target-directory.
Two examples, on a git push in source repository you want certain files to be pushed into destination repository:
- Specify a directory in the
sourceto be pushed todestination - Generate some files using another GitHub Action (e.g. MarkDown to PDF) and you want to push the PDFs across
source or destination can be private.
Table of contents
General flow
There are two examples:
- Using SSH deploy keys (recommended, a bit harder to setup): push-to-another-repository-deploy-keys-example. The configuration is in the file .github/workflows/ci.yml
- Using a Personal Access Token (first style, not recommended but easier to setup: push-to-another-repository-example. The configuration is in the file .github/workflows/ci.yml
In those examples the file build.sh is executes which creates a new directory output/ and this directory is copied across the destination repository
Before using the GitHub Action it is needed to set up either the Personal Access Token or the SSH Keys as described below.
⚠️ Please bear in mind: files in the target repository's specified directory are deleted unless the option target-directory is used (in this case only the files for this directory are deleted).
There are different variables to set up the behaviour:
Usage
source-directory (argument)
Directory that the GitHub Action will push files from. Note: it can be . to push all the repository but read the FAQ!
destination-github-username (argument)
To output to a repository such as https://github.com/cpina/push-to-another-repository-output this variable would be cpina.
destination-repository-name (argument)
To output to a repository such as https://github.com/cpina/push-to-another-repository-output this variable would be push-to-another-repository-output
⚠️: the GitHub Action currently deletes all the files and directories in the destination repository. The idea is to copy from an output directory into the destination-repository-name having a copy without any previous files there.
user-email (argument)
The email that will be used for the commit in the destination-repository-name. Used for the "Author" of the generated commit.
user-name (argument) [optional]
The name that will be used for the commit in the destination-repository-name. If not specified, the destination-github-username will be used instead.
destination-repository-username (argument) [optional]
The Username/Organization for the destination repository, if different from destination-github-username. For the repository https://github.com/cpina/push-to-another-repository-output is cpina.
target-branch (argument) [optional]
The branch name for the destination repository. It defaults to main.
commit-message (argument) [optional]
The commit message to be used in the output repository. Optional and defaults to "Update from $REPOSITORY_URL@commit".
The string ORIGIN_COMMIT is replaced by $REPOSITORY_URL@commit.
target-directory (argument) [optional]
The directory to wipe and replace in the target repository. Defaults to wiping the entire repository
Setup
SSH_DEPLOY_KEY Vs. API_TOKEN_GITHUB
The action, entirely executed in your GitHub continuous integration environment, needs to be able to push to the destination repository.
There are two options to do this:
- Create an SSH deploy key. This key is restricted to the destination repository only
- Create a GitHub Personal Authentication Token: the token has access to all your repositories
Someone with write access to your repository or this action, could technically add code to leak the key. Thus, it is recommended to use the SSH deploy key method to minimise repercusions if this was the case.
This action supports both methods to keep backwards compatibility, because in the beginning it only supported the GitHub Personal Authentication token.
Set up using SSH deploy key
Generate the key files
ssh-keygen -t ed25519 -C "your_email@example.com"(the type ed25519 is recommended by GitHub documentation)- ssh will ask for a file path:
Enter file in which to save the key: write a new file name. I suggest the default directory and as a filename:id_github_name_of_your_repositoryto avoid overwriting a previous file. If you will be using this action for multiple repositories, you might want to generate different keys for each one. - Leave the passphrase empty (otherwise we would need to pass the passphrase to the GitHub Action)
Set up the deployment key
Destination repository
- Go to the GitHub page of the destination repository
- Click on "Settings" (settings for the repository, not the account settings)
- On the left-hand side pane click on "Deploy keys"
- Click on "Add deploy key"
- Title: "GitHub Action push to another repository"
- Key: paste the contents of the file with the public key. This was generated in the "Generate the key files" step and the name is "id_github_name_of_your_repository.pub"
- Enable "Allow write access"barbar
Origin repository
- Go to the GitHub page of the origin repository
- On the left-hand side pane click on "Secrets" and then on "Actions"
- Click on "New repository secret"
- Name: "SSH_DEPLOY_KEY"
- Value: paste the contents of the file with the private key. This was generated in the "Generate the key files" step and the name is "id_github_name_of_your_repository"
Set up using personal access token
You don't need to do this if you chose to set up the deploy keys using the steps above. This method is here for compatibility with the initial approach of this GitHub Action. The personal access token would have access to all your repositories, so if it were to be leaked the damage would be greater.
Generate your personal token following the steps:
- Go to the GitHub Settings (on the right-hand side on the profile picture)
- On the left-hand side pane click on "Developer Settings"
- Click on "Personal Access Tokens" (also available at https://github.com/settings/tokens)
- Generate a new token, choose "Repo". Copy the token.
Then make the token available to the Github Action following the steps:
- Go to the GitHub page for the repository that you push from. Click on "Settings"
- On the left-hand side pane click on "Secrets" then "Actions"
- Click on "New repository secret"
- Name: "API_TOKEN_GITHUB"
- Value: paste the token that you copied earlier
Example usage
- name: Pushes to another repository
uses: cpina/github-action-push-to-another-repository@main
env:
SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
with:
source-directory: 'output'
destination-github-username: 'cpina'
destination-repository-name: 'pandoc-test-output'
user-email: carles3@pina.cat
target-branch: main
(you only need SSH_DEPLOY_KEY or API_TOKEN_GITHUB depending on the method that you used)
Working example:
It generates files from: https://github.com/cpina/push-to-another-repository-deploy-keys-example
To: https://github.com/cpina/push-to-another-repository-output