Configuration

Input Variables (v3)

Core Use

Name	Required?	Default	Example
target_sync_branch	✅		'master', 'main', 'my-branch'
target_repo_token	✅		${{ secrets.GITHUB_TOKEN }}
upstream_repo_access_token			${{ secrets.NAME_OF_TOKEN }}
upstream_sync_repo	✅		'aormsby/Fork-Sync-With-Upstream-action'
upstream_sync_branch	✅		'master', 'main', 'my-branch'
test_mode		false	true / false

Important: target_repo_token must always be passed with ${{ secrets.GITHUB_TOKEN }} as its value. See private setup notes below for details regarding persisted credentials.

Advanced Use

Name	Required?	Default	Example
host_domain	✅	'github.com'	'github.com'
shallow_since	✅	'1 month ago'	'2 days ago', '3 weeks 7 hours ago'
target_branch_checkout_args			'--recurse-submodules'
git_log_format_args		'--pretty=oneline'	'--graph --pretty=oneline'
upstream_pull_args			'--ff-only --tags'
target_branch_push_args			'--force'
git_config_user		'GH Action - Upstream Sync'
git_config_email		'[email protected]'
git_config_pull_rebase		'false'

shallow_since -> Value should match the time between workflow runs to get the history depth required (but no more) for a good check of new commits to sync. Any longer time would fetch unnecessary commit histories.

Git Config Settings

Some basic git config settings must be in place to pull and push data during the action. As seen above, the user/email/rebase inputs are required and have default values. When this action is finished running, they are reset to their values before the action.

Set any git config values to null to skip their configuration during the Fork Sync step.

Output Variables

Name	Output	Description
has_new_commits	true/false	Outputs true if new commits were found in the remote repo, false if target repo already has the latest updates.

The syntax for checking outputs in workflows is very specific. If you have syntax problems, your output checks won't work as expected. Please note the different ways to access and compare output values in these samples--

    - name: New commits found
      if: steps.sync.outputs.has_new_commits == 'true'
      run: echo "New commits were found to sync."
    
    - name: No new commits
      if: steps.sync.outputs.has_new_commits == 'false'
      run: echo "There were no new commits."
      
    - name: Show value of 'has_new_commits'
      run: echo ${{ steps.sync.outputs.has_new_commits }}

New outputs can be added on request. Please open an issue describing your needs.

Upstream Repo Setup

Public

In the sample workflow, I use Github's actions/checkout action as the first step in order to quickly check out the target repo. Unless you have a custom checkout step in place, it's pretty likely you'll be using this same step.

If your upstream repo is public, you can use a rather simple setup for checkout.

- name: Checkout target repo
  uses: actions/checkout@v2
  with:
    ref:  my-target-branch

Setting the ref input to the same value your target_sync_branch will check out that branch at its head, and you can be confident you have the right branch checked out for your work. The sync action also tries to check out your selected branch as a fallback measure.

fetch-depth

However, the sync action can fail if your checkout ref doesn't match your target sync branch. The checkout action with a ref is scoped to only checkout the given branch. You get around this by modifying the fetch depth settings in the checkout step to fetch history for all branches and tags.

with:
  ref:  my-target-branch
  `fetch-depth:0`

This is most likely to be needed when you're running a workflow that does more with other branches than just syncing.

Caution: Fetching all history is probably slow and undesirable for very large repos. Use this option wisely.

Private

For private upstream repos you'll need to modify checkout and include a private repo token.

This requirement comes out of the checkout's persist-credentials option. It's set to true by default - which is oftne fine - but it's a problem for the sync action. The URL for the upstream repo is set using the auth token passed into upstream_repo_access_token, and you would expect that to give you access. But because the checkout step persists the target repo's auth token throughout the workflow, the action runner tries to use it for everything, which results in private upstream access always failing.

To fix this, you have to set persist-credentials: false in the checkout step.

  with:
    ref:  my-target-branch
    persist-credentials: false

Setting this input also works when using public repos, but it's not strictly necessary.

Now your target repo credentials won't persist after the initial checkout.

This is why the sync action requires you to set target_repo_token: ${{ secrets.GITHUB_TOKEN }}! When the action pushes the synced commits later, it needs the correct authorization. Setting the target repo token was mad a requirement to clear up confusion around this issue.

Pro Tip: The action's Test Mode will help you verify that your setup is correct! If there are any issues in the checkout or sync action configurations, the tests will suggest which input values to check to solve the problem.