Merge branch 'ssh-deploy-key'

Dockerfile

@@ -1,6 +1,6 @@
 FROM alpine:latest
 
-RUN apk add --no-cache git
+RUN apk add --no-cache git openssh-client
 
 COPY entrypoint.sh /entrypoint.sh
 

README.md

@@ -1,14 +1,18 @@
 # github-action-push-to-another-repository
 
-When to use this GitHub Action? It is useful in case that you have a GitHub repository with a a directory that you want to push to another GitHub repository using GitHub Actions (automated on push, for example). It is also useful if using GitHub Actions you generate certain files that you want to push to another GitHub 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.
 
 Flow:
 
-The [example repository](https://github.com/cpina/push-to-another-repository-example) has a MarkDown file [main.md](https://github.com/cpina/push-to-another-repository-example/blob/main/main.md)), during the [GitHub Actions flow](https://github.com/cpina/push-to-another-repository-example/blob/main/.github/workflows/ci.yml#L19) it executes [build.sh](https://github.com/cpina/push-to-another-repository-example/blob/main/build.sh) and the output/ directory (configurable via [source-directory](https://github.com/cpina/push-to-another-repository-example/blob/main/.github/workflows/ci.yml#L27) appears in the [output repository](https://github.com/cpina/push-to-another-repository-output).
+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
 
-Please bear in mind: files in the target repository's specified directory are deleted. This is to make sure that it contains only the generated files in the last run without previously generated files.
+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).
 
-There are different variables to setup the behaviour:
+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.
+
+There are different variables to set up the behaviour:
 
 ## Inputs
 ### `source-directory` (argument)
@@ -42,34 +46,67 @@ 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
 
-### `API_TOKEN_GITHUB` (environment)
-E.g.:
-  `API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}`
+### `SSH_DEPLOY_KEY` or `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.
+
+## Setup with 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
+
+#### 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 the 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"
+* 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.
 
-⚠️  : The "Personal Access Token" that you just generated gives access to any repository to which you have access (it's not possible to restrict it to one repository). Technically anyone with *write* access to a repository where the token is made available via "Add a new secret" (next step), might manage to access it. The action also uses the token; you can verify how it is used in entrypoint.sh . Possible work arounds if you don't want to use the personal access token:
- * Use this action's `ssh-deploy-key` branch. I need to write documentation for this (possibly the next 24 hours, but you create a deploy key and add the private key as a variable in the pushing repository. See updates on https://github.com/cpina/github-action-push-to-another-repository/issues/66
- * Use this other action: https://github.com/leigholiver/commit-with-deploy-key
- * Create a new GitHub user, give access to your destination repository and use this user for the personal access token
-
-**News: ** new branch https://github.com/cpina/github-action-push-to-another-repository/tree/ssh-deploy-key allowing to use SSH_DEPLOY_KEYS. I will do some more testing and write documentation soon.
-
 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"
-* Click on "Add a new secret" and name it "API_TOKEN_GITHUB"
-
+* 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
 ```yaml
       - 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'
@@ -78,13 +115,14 @@ Then make the token available to the Github Action following the steps:
           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:
 
-https://github.com/cpina/push-to-another-repository-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:
-https://github.com/cpina/push-to-another-repository-example
+https://github.com/cpina/push-to-another-repository-deploy-keys-example
 
 To:
 https://github.com/cpina/push-to-another-repository-output

entrypoint.sh

@@ -26,6 +26,31 @@ then
 	USER_NAME="$DESTINATION_GITHUB_USERNAME"
 fi
 
+# Verify that there (potentially) some access to the destination repository
+# and set up git (with GIT_CMD variable) and GIT_CMD_REPOSITORY
+if [ -n "${SSH_DEPLOY_KEY:=}" ]
+then
+	# Inspired by https://github.com/leigholiver/commit-with-deploy-key/blob/main/entrypoint.sh , thanks!
+	mkdir --parents "$HOME/.ssh"
+	DEPLOY_KEY_FILE="$HOME/.ssh/deploy_key"
+	echo "${SSH_DEPLOY_KEY}" > "$DEPLOY_KEY_FILE"
+	chmod 600 "$DEPLOY_KEY_FILE"
+
+	SSH_KNOWN_HOSTS_FILE="$HOME/.ssh/known_hosts"
+	ssh-keyscan -H github.com > "$SSH_KNOWN_HOSTS_FILE"
+
+	export GIT_SSH_COMMAND="ssh -i "$DEPLOY_KEY_FILE" -o UserKnownHostsFile=$SSH_KNOWN_HOSTS_FILE"
+
+	GIT_CMD_REPOSITORY="git@$GITHUB_SERVER:$DESTINATION_REPOSITORY_USERNAME/$DESTINATION_REPOSITORY_NAME.git"
+
+elif [ -n "${API_TOKEN_GITHUB:=}" ]
+	GIT_CMD_REPOSITORY="https://$DESTINATION_REPOSITORY_USERNAME:the_api_token@$GITHUB_SERVER/$DESTINATION_REPOSITORY_USERNAME/$DESTINATION_REPOSITORY_NAME.git"
+then
+	echo "::error::API_TOKEN_GITHUB and SSH_DEPLOY_KEY are empty. Please fill one (recommended the SSH_DEPLOY_KEY"
+	exit 1
+fi
+
+
 CLONE_DIR=$(mktemp -d)
 
 echo "[+] Git version"
@@ -37,12 +62,12 @@ git config --global user.email "$USER_EMAIL"
 git config --global user.name "$USER_NAME"
 
 {
-	git clone --single-branch --branch "$TARGET_BRANCH" "https://$DESTINATION_REPOSITORY_USERNAME:$API_TOKEN_GITHUB@$GITHUB_SERVER/$DESTINATION_REPOSITORY_USERNAME/$DESTINATION_REPOSITORY_NAME.git" "$CLONE_DIR"
+	git clone --single-branch --branch "$TARGET_BRANCH" "$GIT_CMD_REPOSITORY" "$CLONE_DIR"
 } || {
 	echo "::error::Could not clone the destination repository. Command:"
-	echo "::error::git clone --single-branch --branch $TARGET_BRANCH https://$DESTINATION_REPOSITORY_USERNAME:the_api_token@$GITHUB_SERVER/$DESTINATION_REPOSITORY_USERNAME/$DESTINATION_REPOSITORY_NAME.git $CLONE_DIR"
-	echo "::error::(Note that USER_NAME and API_TOKEN is redacted by GitHub)"
-	echo "::error::Please verify that the target repository exist AND that it contains the destination branch name, and is accesible by the API_TOKEN_GITHUB"
+	echo "::error::git clone --single-branch --branch $TARGET_BRANCH $GIT_CMD_REPOSITORY $CLONE_DIR"
+	echo "::error::(Note that if they exist USER_NAME and API_TOKEN is redacted by GitHub)"
+	echo "::error::Please verify that the target repository exist AND that it contains the destination branch name, and is accesible by the API_TOKEN_GITHUB OR SSH_DEPLOY_KEY"
 	exit 1
 
 }
@@ -117,4 +142,4 @@ git diff-index --quiet HEAD || git commit --message "$COMMIT_MESSAGE"
 
 echo "[+] Pushing git commit"
 # --set-upstream: sets de branch when pushing to a branch that does not exist
-git push "https://$USER_NAME:$API_TOKEN_GITHUB@$GITHUB_SERVER/$DESTINATION_REPOSITORY_USERNAME/$DESTINATION_REPOSITORY_NAME.git" --set-upstream "$TARGET_BRANCH"
+git push "$GIT_CMD_REPOSITORY" --set-upstream "$TARGET_BRANCH"