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 2025-09-05 00:05:45 -06:00
Code Issues Packages Projects Releases Wiki Activity

Minor text edits to README

Browse Source 
Updated to end of Setup using SSH deploy key section.
This commit is contained in:
jen-thomas 2022-09-01 11:34:05 +01:00 committed by GitHub
parent cc9ee933e7
commit c802d44335
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
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,7 +168,7 @@ 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