{"id":18989154,"url":"https://github.com/s0/git-publish-subdir-action","last_synced_at":"2025-05-15T17:08:23.353Z","repository":{"id":42815750,"uuid":"216143574","full_name":"s0/git-publish-subdir-action","owner":"s0","description":"GitHub Action to push a subdirectory as a branch to any git repo (e.g. for GitHub Pages)","archived":false,"fork":false,"pushed_at":"2025-05-15T10:03:45.000Z","size":1216,"stargazers_count":229,"open_issues_count":20,"forks_count":44,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-05-15T17:08:15.750Z","etag":null,"topics":["actions","git","github","github-actions","github-pages","ssh"],"latest_commit_sha":null,"homepage":"https://github.com/marketplace/actions/push-git-subdirectory-as-branch","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"s0"}},"created_at":"2019-10-19T03:30:43.000Z","updated_at":"2025-05-06T10:23:31.000Z","dependencies_parsed_at":"2023-12-19T03:24:31.972Z","dependency_job_id":"3355179c-8371-435d-bedc-aaed41fe7792","html_url":"https://github.com/s0/git-publish-subdir-action","commit_stats":{"total_commits":200,"total_committers":12,"mean_commits":"16.666666666666668","dds":"0.16000000000000003","last_synced_commit":"61eb9e6420447e7cbf010f7cce37103665c46bfa"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fgit-publish-subdir-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fgit-publish-subdir-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fgit-publish-subdir-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fgit-publish-subdir-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s0","download_url":"https://codeload.github.com/s0/git-publish-subdir-action/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","git","github","github-actions","github-pages","ssh"],"created_at":"2024-11-08T17:05:27.009Z","updated_at":"2025-05-15T17:08:18.344Z","avatar_url":"https://github.com/s0.png","language":"TypeScript","readme":"# GitHub Action: Push git subdirectory as branch\n\n[![](https://github.com/s0/git-publish-subdir-action/workflows/Scheduled%20tests/badge.svg)](https://github.com/s0/git-publish-subdir-action/actions?workflow=Scheduled+tests) [![codecov](https://codecov.io/gh/s0/git-publish-subdir-action/branch/master/graph/badge.svg)](https://codecov.io/gh/s0/git-publish-subdir-action) [![](https://raw.githubusercontent.com/s0/git-publish-subdir-action/gh-badges/drift.svg)](https://github.com/s0/libyear-node-action) [![](https://raw.githubusercontent.com/s0/git-publish-subdir-action/gh-badges/releases.svg)](https://github.com/s0/libyear-node-action)\n\nThis GitHub Action will take any subdirectory in your repository, and push it as the contents of a git branch to a repository and branch of your choosing, either over SSH or to the current repo.\n\nYou could use this for example to:\n\n* Publishing a subdirectory to a repo's `gh-pages` branch, after optionally running a build step.\n* Publishing build artifacts / binaries to another repository\n\nThe target repository can be anywhere accessible by a [Git SSH URL](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) (or the current repository).\nIf the target branch doesn't exist yet, it will be created automatically.\n\n## Usage\n\nSimply include the action `s0/git-publish-subdir-action@develop` in the appropriate point in your workflow, and pass in the required configuration options:\n\n```yml\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    steps:\n\n    # Any prerequisite steps\n    - uses: actions/checkout@master\n\n    # Deploy to local repo\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: self\n        BRANCH: gh-pages\n        FOLDER: build\n        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n    # Deploy to another repo\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: git@github.com:owner/repo.git\n        BRANCH: gh-pages\n        FOLDER: build\n        SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_PRIVATE_KEY }}\n        KNOWN_HOSTS_FILE: resources/known_hosts # Needed if target repo is not on github.com\n```\n\n## Examples\n\n### When pushed to master, push `/public/site` to the `gh-pages` branch on the same repo\n\n```yml\nname: Deploy to GitHub Pages\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    name: Deploy to GitHub Pages\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@master\n\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: self\n        BRANCH: gh-pages\n        FOLDER: public/site\n        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n\n### When pushed to master, push the contents of `/public/site` to the `www` folder on the  `gh-pages` branch on the same repo\n\n```yml\nname: Deploy to GitHub Pages\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    name: Deploy to GitHub Pages\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@master\n\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: self\n        BRANCH: gh-pages\n        FOLDER: public/site\n        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n        TARGET_DIR: www\n```\n\n### When pushed to master, run a build step, then push `/build` to the `gh-pages` branch on another repo on GitHub\n\n```yml\nname: Deploy to GitHub Pages\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    name: Deploy to GitHub Pages\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@master\n    - name: Use Node.js\n      uses: actions/setup-node@main\n      with:\n        node-version: 20.x\n    - name: npm install and build\n      run: |\n        npm install\n        npm run build\n\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: git@github.com:owner/repo.git\n        BRANCH: gh-pages\n        FOLDER: build\n        SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_PRIVATE_KEY }}\n```\n\nNote: the SSH Key needs to have write access to the given repo. It's recommended you use [Deploy Keys](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) for this (see below),\nand store the SSH private key as as Secret in the repository settings.\n\n\n### When pushed to master, run a build step, then push `/dist` to the `artifacts` branch on a repo hosted at mydomain.com\n\n```yml\nname: Deploy to GitHub Pages\non:\n  push:\n    branches:\n      - master\n\njobs:\n  deploy:\n    name: Deploy to GitHub Pages\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@master\n    - name: Use Node.js\n      uses: actions/setup-node@main\n      with:\n        node-version: 20.x\n    - name: npm install and build\n      run: |\n        npm install\n        npm run build\n\n    - name: Deploy\n      uses: s0/git-publish-subdir-action@develop\n      env:\n        REPO: git@mydomain.com:path/to/repo.git\n        BRANCH: artifacts\n        FOLDER: dist\n        SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_PRIVATE_KEY }}\n        KNOWN_HOSTS_FILE: resources/known_hosts # Path relative to the root of the repository\n```\n\nYou can generate a `known_hosts`  file for a given domain by using `ssh-keyscan`, e.g:\n\n```bash\n\u003e ssh-keyscan github.com\n# github.com:22 SSH-2.0-babeld-f345ed5d\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==\n# github.com:22 SSH-2.0-babeld-f345ed5d\n# github.com:22 SSH-2.0-babeld-f345ed5d\n```\n\n\n## Configuration\n\nAll configuration options are passed in via `env`, as environment variables.\n\n| Env Variable       | Description                                            | Required?     |\n| ------------------ | ------------------------------------------------------ | ------------- |\n| `REPO`             | Either `self`, or an SSH url to the target repository. | Yes           |\n| `BRANCH`           | The target branch to publish to.                       | Yes           |\n| `FOLDER`           | The target subfolder you would like to publish         | Yes           |\n| `SSH_PRIVATE_KEY`  | The private key that should be used to authenticate on SSH. Don't include this directly in the workflow file, instead you must use [Secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) | When `REPO` is an SSH URL |\n| `KNOWN_HOSTS_FILE` | Path to a file in the repository that contains the known SSH fingerprints for the target host. | When the target host is not github.com |\n| `GITHUB_TOKEN`     | Should always be equal to `${{ secrets.GITHUB_TOKEN }}` | When `REPO = self` |\n| `SQUASH_HISTORY`   | If set to `true`, all previous commits on the target branch will be discarded. For example, if you are deploying a static site with lots of binary artifacts, this can help the repository becoming overly bloated. | No |\n| `SKIP_EMPTY_COMMITS` | If set to `true`, commits will only be pushed if the contents of the target branch will be changed as a result. This is useful if, for example, you'd like to easily track which upstream changes result in changes to your target branch. | No |\n| `MESSAGE`          | A custom template to use as the commit message pushed to the target branch. See [custom commit messages](#custom-commit-messages). | No |\n| `TAG` | A string following the [git-check-ref-format](https://git-scm.com/docs/git-check-ref-format) that tags the commit with a lightweight git-tag. | No |\n| `CLEAR_GLOBS_FILE` | An optional path to a file to use as a list of globs defining which files to delete when clearing the target branch. | No |\n| `COMMIT_NAME` | The username the autogenerated commit will use. If unset, uses the commit pusher's username. | No |\n| `COMMIT_EMAIL` | The email the autogenerated commit will use. If unset, uses the commit pusher's email. | No |\n| `TARGET_DIR` | An optional string to change the directory where the files are copied to. | No |\n\n\n### Custom commit messages\n\nYou can specify a custom string to use in the commit message\nwhen pushing to your target repository.\nThese strings support a number of placeholders that will be replaces with\nrelevant values:\n\n| Placeholder        | Description                                           |\n| ------------------ | ----------------------------------------------------- |\n| `{target-branch}`  | The name of the target branch being updated           |\n| `{sha}`            | The 7-character sha of the HEAD of the current branch |\n| `{long-sha}`       | The full sha of the HEAD of the current branch        |\n| `{msg}`            | The commit message for the HEAD of the current branch |\n\nExample Usage:\n\n```yml\njobs:\n  deploy:\n    - uses: s0/git-publish-subdir-action@develop\n      env:\n        # ...\n        MESSAGE: \"This updates the content to the commit {sha} that had the message:\\n{msg}\"\n```\n\n### Custom clear operations\n\nBy default, this action will clear the target branch of any pre-existing files,\nand only keep those that are defined in the target `FOLDER` when the action was\nrun.\n\nThis can now be overwritten by specifying a file with a custom list of globs to\ndefine which files should be deleted from the target branch before copying the\nnew files over.\n\nThe environment variable `CLEAR_GLOBS_FILE` should point to the path of the\nglob file (which can have any name) relative to root of the target repository.\n\n**Note: using this feature will disable the default functionality of deleting\neverything, and you will need to specify exactly what needs to be deleted.**\n\n#### Examples\n\n1. Default behaviour:\n\n   ```\n   **/*\n   !.git\n   ```\n\n1. Default behaviour with a custom target directory:\n\n   ```\n   target_dir/**/*\n   !.git\n   ```\n\n1. Delete everything except the `.git` and `foobar` folder:\n\n   ```\n   **/*\n   !.git\n   !foobar/**/*\n   ```\n\n1. Only delete the folder `folder` (except `folder/a`), and also delete anything\n   matching `ini*al2`:\n\n   ```\n   folder/*\n   !folder/a\n   ini*al2\n   ```\n\nFor clarity, if we have the file `.clear-target-files`:\n\n```\nfolder/*\n!folder/a\nini*al2\n```\n\nAnd the workflow file `.github/workflows/ci.yml`:\n\n```yml\njobs:\n  deploy:\n    - uses: s0/git-publish-subdir-action@develop\n      env:\n        # ...\n        CLEAR_GLOBS_FILE: \".clear-target-files\"\n```\n\nAnd the target branch already had the files:\n\n```\ninitial1\ninitial2\nfolder/a\nfolder/b\n```\n\nThen the files that would remain would be:\n\n```\nfolder/a\ninitial1\n```\n\nAn empty file can be used to indicate that the branch should not be cleared at\nall.\n\n\n\n## Usage with [Deploy Keys](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys)\n\nWhen pushing to other repositories on GitHub or GitHub Enterprise,\nthe recommended mechanism is to use [Deploy Keys](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) rather than your own private SSH key.\nDeploy keys are SSH keys that can be added to specific repositories to be given write access to only\nthose repositories.\nThis is preferable to adding your own personal ssh private key to a repository's secrets store,\nas it means that any actions that have access to this repository's secrets can only push\nto repositories that have explicitly had the SSH key added as a deploy key,\nand not *all* repositories that your user account have access to.\n\nUse `ssh-keygen` to create a new ssh key, add these to GitHub in the relevant repo's deploy keys and Secrets, then delete them off your computer.\n\n```\n\u003e cd /tmp\n\u003e ssh-keygen -t ed25519\nGenerating public/private ed25519 key pair.\nEnter file in which to save the key (/home/sam/.ssh/id_ed25519): temp-deploy-key\nEnter passphrase (empty for no passphrase):\nEnter same passphrase again:\nYour identification has been saved in temp-deploy-key.\nYour public key has been saved in temp-deploy-key.pub.\nThe key fingerprint is:\nSHA256:tQBSeWjZ4Er4YYjK4XQ4npfiK2xJPJLbGjTsYJq/9JI sam@optimus\nThe key's randomart image is:\n+--[ED25519 256]--+\n|    ..+*         |\n| ..o o=.o        |\n|.=o.+.... .      |\n|B =+.o   o .     |\n|+% oo   S .      |\n|X=+              |\n|B=+.             |\n|oBE.             |\n|+ooo.            |\n+----[SHA256]-----+\n\u003e cat temp-deploy-key.pub\nssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX user@localhost\n\u003e cat temp-deploy-key\n-----BEGIN OPENSSH PRIVATE KEY-----\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=\n-----END OPENSSH PRIVATE KEY-----\n```\n","funding_links":["https://github.com/sponsors/s0"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs0%2Fgit-publish-subdir-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs0%2Fgit-publish-subdir-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs0%2Fgit-publish-subdir-action/lists"}