actions/github-action-push-to-another-repository
1
0
Fork 0
mirror of https://github.com/cpina/github-action-push-to-another-repository.git synced 2024-12-23 00:26:09 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'improve-documentation' of github.com:cpina/github-action-push-to-another-repository into improve-documentation

Browse Source
This commit is contained in:
Carles Pina i Estany 2022-09-04 23:36:36 +01:00
commit 36c541c94b
1 changed files with 55 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@ -1,13 +1,13 @@
# github-action-push-to-another-repository # 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. 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.
For example, on a git push in a `source` repository, you want certain files to be pushed into a `destination` repository. A couple of examples of this could be:
* Specifying a directory in the `source` to be pushed to `destination`
* Generating some files using another GitHub Action (e.g. MarkDown to PDF) and pushing the PDFs across
Please read the documentation to understand which files and commits are kept in the destination repository and `target-directory`. 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 `source` to be pushed to `destination`
* 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. `source` or `destination` can be private.
## Table of contents ## Table of contents
@ -17,48 +17,48 @@ Two examples, on a git push in `source` repository you want certain files to be
## General flow ## General flow
There are two examples: There are two examples:
* Using SSH deploy keys (recommended, a bit harder to setup): [push-to-another-repository-deploy-keys-example](https://github.com/cpina/push-to-another-repository-deploy-keys-example). The configuration is in the file [.github/workflows/ci.yml](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml#L21) * Using SSH deploy keys (recommended, a bit harder to set up): [push-to-another-repository-deploy-keys-example](https://github.com/cpina/push-to-another-repository-deploy-keys-example). The configuration is in the file [.github/workflows/ci.yml](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml#L21)
* Using a Personal Access Token (first style, not recommended but easier to setup: [push-to-another-repository-example](https://github.com/cpina/push-to-another-repository-example). The configuration is in the file [.github/workflows/ci.yml](https://github.com/cpina/push-to-another-repository-example/blob/main/.github/workflows/ci.yml#L21) * Using a Personal Access Token (first iteration, not recommended but easier to set up: [push-to-another-repository-example](https://github.com/cpina/push-to-another-repository-example). The configuration is in the file [.github/workflows/ci.yml](https://github.com/cpina/push-to-another-repository-example/blob/main/.github/workflows/ci.yml#L21)
In those examples the file [build.sh](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/build.sh) is executes which creates a new directory `output/` and this directory is copied across the [destination repository](https://github.com/cpina/push-to-another-repository-output) In the above examples, the file [build.sh](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/build.sh) is executed, which creates a new directory `output/` and this directory is copied across to the [destination repository](https://github.com/cpina/push-to-another-repository-output)
Before using the GitHub Action **it is needed to set up either the Personal Access Token or the SSH Keys as described below.** Before using the GitHub Action, **either the Personal Access Token or the SSH Keys need to be set up as described below.**
:warning: 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). :warning: Please bear in mind that the files in the specified directory of the target repository 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: There are different variables to set up the behaviour:
## Usage ## Usage
### `source-directory` (argument) ### `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! 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) ### `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`. Username/Organization of the GitHub repository that will be used for the `destination` repository. 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) ### `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` Name of the `destination` repository. 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`
:warning:: 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. :warning:: 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`, removing all pre-existing files.
### `user-email` (argument) ### `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. The email that will be used for the commit to the destination-repository-name. Used for the "Author" of the generated commit.
### `user-name` (argument) [optional] ### `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. The name that will be used for the commit to the destination-repository-name. If not specified, the `destination-github-username` will be used instead.
### `destination-repository-username` (argument) [optional] ### `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`. 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` this variable would be `cpina`.
### `target-branch` (argument) [optional] ### `target-branch` (argument) [optional]
The branch name for the destination repository. It defaults to `main`. The branch name for the destination repository. It defaults to `main`.
### `commit-message` (argument) [optional] ### `commit-message` (argument) [optional]
The commit message to be used in the output repository. Optional and defaults to "Update from $REPOSITORY_URL@commit". The commit message to be used in the output repository. Optional and defaults to "Update from ORIGIN_COMMIT".
The string `ORIGIN_COMMIT` is replaced by `$REPOSITORY_URL@commit`. The string `ORIGIN_COMMIT` is replaced by `$ORIGIN_REPOSITORY_URL@commit`.
### `target-directory` (argument) [optional] ### `target-directory` (argument) [optional]
The directory to wipe and replace in the target repository. Defaults to wiping the entire repository The directory to wipe and replace in the target repository. Defaults to wiping the entire repository.
## Setup ## Setup
### `SSH_DEPLOY_KEY` Vs. `API_TOKEN_GITHUB` ### `SSH_DEPLOY_KEY` Vs. `API_TOKEN_GITHUB`
@ -66,20 +66,20 @@ The action, entirely executed in your GitHub continuous integration environment,
There are two options to do this: There are two options to do this:
* Create an SSH deploy key. This key is restricted to the destination repository only * 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 * 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 the impact* if this was the case. 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 the impact* if this were to happen.
This action supports both methods to keep backwards compatibility, because in the beginning it only supported the GitHub Personal Authentication token. 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 ### Setup using SSH deploy key
Recommended, a bit harder (more steps) to setup compared with the Personal Access Token. Recommended, but the setup has a few more steps compared with the Personal Access Token option.
#### Generate the key files #### Generate the key files
* In your computer terminal generate an ssh key using: `ssh-keygen -t ed25519 -C "your_email@example.com"` (the type ed25519 is recommended by [GitHub documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key)). * In your computer terminal, generate an ssh key using: `ssh-keygen -t ed25519 -C "your_email@example.com"` (the type ed25519 is recommended by [GitHub documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key)).
* 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_destination_repository}` to 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. For the repository `https://github.com/cpina/push-to-another-repository-example/` you could use `id_github_push-to-another-repository-example`. * 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_destination_repository}` to 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. For the repository `https://github.com/cpina/push-to-another-repository-example/`, `id_github_push-to-another-repository-example` could be used.
* Leave the passphrase empty (otherwise the GitHub Action cannot use it) * Leave the passphrase empty (otherwise the GitHub Action cannot use it)
Example: Example:
@ -111,7 +111,7 @@ The key's randomart image is:
carles@pinux:~$ carles@pinux:~$
``` ```
This has generated two files, the ssh public key and private key: This has generated two files, the public and private ssh keys:
``` ```
carles@pinux:~$ ls -l /home/carles/.ssh/id_github_push-to-another-repository* carles@pinux:~$ ls -l /home/carles/.ssh/id_github_push-to-another-repository*
-rw------- 1 carles carles 411 Jul 28 09:40 /home/carles/.ssh/id_github_push-to-another-repository -rw------- 1 carles carles 411 Jul 28 09:40 /home/carles/.ssh/id_github_push-to-another-repository
@ -123,7 +123,7 @@ carles@pinux:~$
#### Destination repository #### Destination repository
In this section we will add the generated public key in the destination repository. This is to make the Action able to push there. Text instructions: In this section we will add the generated public key to the destination repository. This allows the Action to push there. Text instructions:
* Go to the GitHub page of the **destination** repository (e.g. https://github.com/cpina/push-to-another-repository-output) * Go to the GitHub page of the **destination** repository (e.g. https://github.com/cpina/push-to-another-repository-output)
* Click on "Settings" (settings for the repository, not the account settings) * Click on "Settings" (settings for the repository, not the account settings)
@ -149,7 +149,7 @@ In this section we will add the generated public key in the destination reposito
* Go to the GitHub page of the origin repository (e.g. https://github.com/cpina/push-to-another-repository-deploy-keys-example) * Go to the GitHub page of the origin repository (e.g. https://github.com/cpina/push-to-another-repository-deploy-keys-example)
* Click on the "Settings" (settings for the repository, not the account settings)) * Click on the "Settings" (settings for the repository, not the account settings)
![Screenshot-settings](docs/screenshots/ssh-key-10.png) ![Screenshot-settings](docs/screenshots/ssh-key-10.png)
@ -168,11 +168,11 @@ In this section we will add the generated public key in the destination reposito
The GitHub Action will detect the SSH_DEPLOY_KEY secret and use the private key to push to the destination directory. The GitHub Action will detect the SSH_DEPLOY_KEY secret and use the private key to push to the destination directory.
Please read the [Troubleshooting](#troubleshooting) section if you encounter problems to find how to debug possible problems. Please read the [Troubleshooting](#troubleshooting) section if you encounter problems, to find how to debug possible problems.
### Set up using personal access token ### 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 (push to the same repositories that the Personal Access Token owner has access and other possible associated permissions). On the other hand the setup is a bit easier because it does not involve creating the key. This does not need to be done 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 (it would allow pushes to the same repositories that the Personal Access Token owner has access and other possible associated permissions). On the other hand, the setup is a bit easier because it does not involve creating the deploy key.
Generate your personal token following the steps: Generate your personal token following the steps:
* Go to the general GitHub Settings (on the right-hand side on the profile picture) * Go to the general GitHub Settings (on the right-hand side on the profile picture)
@ -187,15 +187,15 @@ Generate your personal token following the steps:
![Screenshot-personal-access-token](docs/screenshots/pat-30.png) ![Screenshot-personal-access-token](docs/screenshots/pat-30.png)
* Generate a new token entering a name, Expiration date and choose "Repo". Click the bottom button "Generate token". If you choose an expiration date you will need to create a new token after it. I've chosen in this example "No expiration", use carefully. * Generate a new token entering a name, expiration date and choose "Repo". Click the bottom button "Generate token". If you choose an expiration date you will need to create a new token after this date. I've chosen in this example "No expiration"; this should be used carefully.
![Screenshot-personal-access-token-comment-expiration-scope](docs/screenshots/pat-40.png) ![Screenshot-personal-access-token-comment-expiration-scope](docs/screenshots/pat-40.png)
* The token is displayed, copy it * Copy the displayed token
![Screenshot-personal-access-token-comment-displayed](docs/screenshots/pat-50.png) ![Screenshot-personal-access-token-comment-displayed](docs/screenshots/pat-50.png)
Then make the token available to the GitHub Action following the steps: Then make the token available to the GitHub Action using the following steps:
* Go to the GitHub page for the repository that you push from (**origin repository**). Click on "Settings" for the repository * Go to the GitHub page for the repository that you push from (**origin repository**). Click on "Settings" for the repository
![Screenshot-secrets-actions](docs/screenshots/ssh-key-50.png) ![Screenshot-secrets-actions](docs/screenshots/ssh-key-50.png)
@ -231,37 +231,31 @@ Working example:
https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml
It generates files from: This generates files from:
https://github.com/cpina/push-to-another-repository-deploy-keys-example https://github.com/cpina/push-to-another-repository-deploy-keys-example
To: and pushes them to:
https://github.com/cpina/push-to-another-repository-output https://github.com/cpina/push-to-another-repository-output
## Troubleshooting ## Troubleshooting
### Cannot push to the destination repository ### Cannot push to the destination repository
This is the most common problem. The first suggestion is to follow the steps to create the ssh keys or Personal Access Token and set it up again. This is the most common problem. Carefully read the logs on the GitHub Action pages of the source repositories. The action tries to write the errors and gives possible solutions / hints. The first suggestion is to follow the steps above to create the ssh keys or Personal Access Token, and set it up again, but some problems that have occurred in the past are:
In the GitHub Action pages of the source repository: read carefully the logs. The action tries to write the errors and possible solutions / hints. * User was logged in to GitHub with an account that did not have permission to push into the destination repository. The action could not push (permission denied).
Some problems that had happened in the past:
* User was logged in GitHub with an account that did not have permission to push into the destination repository. The action could not push (permission denied).
* Token expired at some point * Token expired at some point
* ssh generated key pair (public/private) was set in the wrong way, copy-paste errors, etc. * ssh generated key pair (public/private) was set in the wrong way.
* Wrong copy-paste including spaces or other characters that did not belong to the key / token * Wrong copy-paste including spaces or other characters that did not belong to the key / token
The easier way might be to try to follow the steps again.
### How to test the Personal Access Token? ### How to test the Personal Access Token?
This might help understanding if the Personal Access Token that you generated have permissions to push to the destination repository. It could be expired, it could have the wrong permissions. It could be that the user that generated the Personal Access Token did not have permission to push into the destination repository. Test that the Personal Access Token has the correct permissions to push to the destination repository. This can be useful to check that the Personal Access Token has not expired or has the correct permissions.
For this you need the Personal Access Token and then in your terminal: In your terminal do:
``` ```
$ git clone https://YOUR_USERNAME:YOUR_ACCESS_TOKEN@github.com/SOMETHING/REPO $ git clone https://YOUR_USERNAME:YOUR_ACCESS_TOKEN@github.com/SOMETHING/REPO
@ -271,7 +265,7 @@ $ git checkout -b test
$ git push origin test $ git push origin test
``` ```
For example, if the token did not have permission to write (because `repo` was not enabled for this token): For example, if the token did not have permission to write (because `repo` was not enabled for this token), you might see the following:
``` ```
$ git push origin test $ git push origin test
remote: Permission to cpina/qdacco.git denied to cpina. remote: Permission to cpina/qdacco.git denied to cpina.
@ -282,14 +276,14 @@ fatal: unable to access 'https://github.com/cpina/qdacco/': The requested URL re
#### Test connection to GitHub using the key pair #### Test connection to GitHub using the key pair
You should have added the public key into the repository (as SSH deploy key, following the documentation). The public key should have been added into the repository (as an SSH deploy key following the documentation above).
Once done, in your computer: Once done, on your computer:
``` ```
$ ssh -o IdentitiesOnly=yes -i .ssh/id_push-to-another-repository-output_ed25519 git@github.com $ ssh -o IdentitiesOnly=yes -i .ssh/id_push-to-another-repository-output_ed25519 git@github.com
``` ```
Instead of `.ssh/id_push-to-another-repository-output_ed25519` use the file as you created it. This is the **private** key (it does not end with `.pub`). If you used the right private key for the correctly uploaded public key it will print something along the lines of: Instead of `.ssh/id_push-to-another-repository-output_ed25519`, use the file as you created it. This is the **private** key (it does not end with `.pub`). If you used the correct private key for the correctly uploaded public key, it will print something along the lines of:
``` ```
Hi cpina! You've successfully authenticated, but GitHub does not provide shell access. Hi cpina! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed. Connection to github.com closed.
@ -300,19 +294,19 @@ If you see:
git@github.com: Permission denied (publickey). git@github.com: Permission denied (publickey).
``` ```
The public key for this private key is not available on GitHub. the public key for this private key is not available on GitHub.
#### Verify that the key is in the right repository #### Verify that the key is in the correct repository
``` ```
$ ssh-keygen -lf .ssh/id_push-to-another-repository-output_ed25519 $ ssh-keygen -lf .ssh/id_push-to-another-repository-output_ed25519
``` ```
The output will be like: The output will be something like:
``` ```
256 SHA256:SOME_STRING_OF_CHARACTERS carles@pina.cat (ED25519) 256 SHA256:SOME_STRING_OF_CHARACTERS carles@pina.cat (ED25519)
``` ```
This should match what you see in the deploy key of the destination repository. If it does not match the deploy key is not properly set (you used different public/private key, etc.). This should match what you see in the deploy key of the destination repository. If it does not match, the deploy key is not properly set (perhaps different public/private keys were used, for example).
##### Permission of the key ##### Permission of the key
@ -327,9 +321,9 @@ Read/Write
Use `source_directory: .`. This will copy all the source GitHub repository to the destination. Use `source_directory: .`. This will copy all the source GitHub repository to the destination.
:warning: this will also copy `.github/workflows/`! The destination repository will try to execute the action. It will probably fail because the Personal Acccess Token / ssh keys will not be available to the destination repository. :warning: this will also copy `.github/workflows/`! The destination repository will try to execute the action. It will probably fail because the Personal Acccess Token / ssh keys will not be available for the destination repository.
Suggestion if you are using `source_directory: .` is to disable the GitHub Actions in the destination repository. To disable Actions in the destination repository: A suggestion if you are using `source_directory: .` is to disable the GitHub Actions in the destination repository. To disable Actions in the destination repository:
* Go to the destination repository (e.g. https://github.com/cpina/push-to-another-repository-output/settings) * Go to the destination repository (e.g. https://github.com/cpina/push-to-another-repository-output/settings)
* Click on "Settings" * Click on "Settings"
@ -337,13 +331,9 @@ Suggestion if you are using `source_directory: .` is to disable the GitHub Actio
* Click on "Disable actions" * Click on "Disable actions"
* Click on "Save" * Click on "Save"
### How can I copy only some files / only some directories / exclude some files / etc. ### How can I copy only some files / only some directories / exclude some files / etc.?
The GitHub Action has some configuration options, but they will not suit all the possible uses cases for everyone. I'm trying to avoid adding more and more parameters to suit all the use cases and the reason is that it's then hard to test all the parameter combinations. If you need to filter files or directories (exclude files, include only some, etc.) use a step before the action to filter from a temporary directory to the directory that will be pushed. This can be done with "rsync" or any tool that you feel comfortable (could be "rclone" or "find + exec + rm", "find + exec + mv", etc. depending on your needs).
I have limited time to support the action. As much as I try I will not be able to suit everyone. The main priority is to have a stable GitHub Action (when GitHub made changes that affected the Action I tried to solve them as fast as possible) and having a small, single-purpose code helps. I have an open issue to add tests that would help then expanding the Action (see [issue #59](https://github.com/cpina/github-action-push-to-another-repository/issues/59]).
If you need something that it's not possible (exclude files, include only some, etc.) please use a step before the action to filter from a temporary directory to the directory that will be pushed. This can be done with "rsync" or any tool that you feel comfortable (could be "rclone" or "find + exec + rm", "find + exec + mv", etc. depending on your needs).
For example see the step: https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml#L21 For example see the step: https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml#L21
@ -353,9 +343,9 @@ In the step above it installs rsync (depending on your environment it will alrea
It seems that GitHub created a Personal Token with a space character. This would happen if the Personal Token had a `#` or other characters. It seems that GitHub created a Personal Token with a space character. This would happen if the Personal Token had a `#` or other characters.
Please check that no space was copied by mistake to the `API_TOKEN_GITHUB`. If GitHub created a token with `#` or a space inside I suggest to create a new one. Please check that no space was copied by mistake to the `API_TOKEN_GITHUB`. If GitHub created a token with `#` or a space inside, I suggest creating a new one.
The problem, for the curious, is that the Personal Access Token is used in the git URLs and the URLs don't support `#`. The error "URL using bad/illegal format" is coming from curl library used by git. The problem, for those that are curious, is that the Personal Access Token is used in the git URLs and the URLs don't support `#`. The error "URL using bad/illegal format" is coming from the curl library used by git.
Complete information: [issue 70](https://github.com/cpina/github-action-push-to-another-repository/issues/70) Complete information: [issue 70](https://github.com/cpina/github-action-push-to-another-repository/issues/70)