mirror of
https://github.com/cpina/github-action-push-to-another-repository.git
synced 2025-09-03 15:35:45 -06:00
Improve introduction of documentation
This commit is contained in:
Carles Pina i Estany
parent
e775fb8544
commit
fe9db296ac
58
README.md
58
README.md
@ -1,33 +1,47 @@
|
||||
# github-action-push-to-another-repository
|
||||
|
||||
When to use this GitHub Action? It can be used if you have a GitHub repository with a directory that you want to push to another GitHub repository using GitHub Actions (automated on push, for example). It is also useful if when using GitHub Actions, you generate certain files that you want to push to another GitHub repository. For example, if you have MarkDown files and want to generate HTML files, then push them into 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.
|
||||
|
||||
Flow:
|
||||
Please read the documentation to understand which files and commits are kept in the destination repository and `target-directory`.
|
||||
|
||||
There are two example repositories:
|
||||
* [Repository 1](https://github.com/cpina/push-to-another-repository-deploy-keys-example): using SSH deploy keys (recommended)
|
||||
* [Repository 2](https://github.com/cpina/push-to-another-repository-example): using a personal access token setup
|
||||
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
|
||||
|
||||
On a push of the repositories (thanks to the file [.github/workflows/ci.yml](https://github.com/cpina/push-to-another-repository-deploy-keys-example/tree/main/.github/workflows) it uses Pandoc to read the MarkDown file [main.md](https://github.com/cpina/push-to-another-repository-deploy-ssh-example/blob/main/main.md) (via [this step](https://github.com/cpina/push-to-another-repository-example/blob/main/.github/workflows/ci.yml#L19) and the example [build.sh](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/build.sh). build.sh generates the output/ directory configurable via [source-directory](https://github.com/cpina/push-to-another-repository-deploy-keys-example/blob/main/.github/workflows/ci.yml#L27) appears in the [output repository](https://github.com/cpina/push-to-another-repository-output).
|
||||
`source` or `destination` can be private.
|
||||
|
||||
Please bear in mind: files in the target repository's specified directory are deleted. This is to make sure that it contains only the files generated on the last run.
|
||||
## Table of contents
|
||||
|
||||
* [General flow](#general_flow)
|
||||
|
||||
## General flow
|
||||
|
||||
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 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)
|
||||
|
||||
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)
|
||||
|
||||
Before using the GitHub Action **it is needed to set up either the Personal Access Token or the SSH Keys 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).
|
||||
|
||||
There are different variables to set up the behaviour:
|
||||
|
||||
## Inputs
|
||||
## Usage
|
||||
### `source-directory` (argument)
|
||||
From the repository that this Git Action is executed the directory that contains the files to be pushed into the repository.
|
||||
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)
|
||||
For the repository `https://github.com/cpina/push-to-another-repository-output` is `cpina`.
|
||||
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)
|
||||
For the repository `https://github.com/cpina/push-to-another-repository-output` is `push-to-another-repository-output`
|
||||
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:* this 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` 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.
|
||||
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.
|
||||
@ -46,7 +60,8 @@ 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
|
||||
|
||||
### `SSH_DEPLOY_KEY` or `API_TOKEN_GITHUB`
|
||||
## 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:
|
||||
@ -57,14 +72,14 @@ Someone with write access to your repository or this action, could technically a
|
||||
|
||||
This action supports both methods to keep backwards compatibility, because in the beginning it only supported the GitHub Personal Authentication token.
|
||||
|
||||
## Setup with SSH deploy key
|
||||
### Generate the key files
|
||||
### 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](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_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.
|
||||
* Leave the passphrase empty (otherwise we would need to pass the passphrase to the GitHub Action)
|
||||
|
||||
### Set up the deployment key
|
||||
#### Set up the deployment key
|
||||
|
||||
#### Destination repository
|
||||
|
||||
@ -84,7 +99,7 @@ This action supports both methods to keep backwards compatibility, because in th
|
||||
* 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 the 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.
|
||||
|
||||
@ -101,7 +116,7 @@ Then make the token available to the Github Action following the steps:
|
||||
* Name: "API_TOKEN_GITHUB"
|
||||
* Value: paste the token that you copied earlier
|
||||
|
||||
## Example usage
|
||||
#### Example usage
|
||||
```yaml
|
||||
- name: Pushes to another repository
|
||||
uses: cpina/github-action-push-to-another-repository@main
|
||||
@ -126,3 +141,8 @@ https://github.com/cpina/push-to-another-repository-deploy-keys-example
|
||||
|
||||
To:
|
||||
https://github.com/cpina/push-to-another-repository-output
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
## FAQ
|
||||
Loading…
x
Reference in New Issue
Block a user