Automate Your Code with GitHub Actions #7: Repository Splitting and Quick Reference

Who is Bas Steins?

Bas is a software developer and technology trainer based in the triangle between the Netherlands, Germany, and Belgium. For almost two decades, he has been helping people turn their ideas into software and helping other developers write better code. This series is based on his mini-guide "Automate Your Code with GitHub Actions".

Repository Split

This example demonstrates how to use a GitHub Action to split a repository into multiple repositories based on a specific path. This can be useful when you want to separate different parts of a project into their own repositories while maintaining a single source of truth.

For example, if you maintain a monolithic repository of a closed source project and want to open source a specific part of it, you can use this workflow to automatically split the open source part into a separate repository.

What you'll learn

• Using a GitHub Action on the push event
• Publishing content from a repository to another repository

name: 'Repository Split'

on:
  push:
    branches:
      - main
    paths:
      - 'scripts/**'

run-name: >-
  Repository Split

concurrency:
  group: 'scripts'
  cancel-in-progress: false

jobs:
  filter:
    name: 'Publish Script(s)'
    runs-on: ubuntu-latest
    env:
      commit_author_name: 'github-actions[bot]'
      commit_author_email: 'github-actions[bot]@users.noreply.github.com'
      origin: sebst/thatus-wi-2024-mono
      ref: main
      paths: '("scripts/")'
      path_globs: '()'
      rename: '("scripts/.github/:.github/")'
      target: sebst/thatus-wi-2024-split
      PAT_GITHUB_TOKEN: ${{ secrets.PAT_GITHUB_TOKEN }}
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        # Relative path under $GITHUB_WORKSPACE to place the repository
        path: 'origin'
        repository: '${{ env.origin }}'
        ref: ${{ env.ref }}
        # fetch all commits
        fetch-depth: 0
        fetch-tags: false
        # use default token or i.e. ${secrets.PERSONAL_ACCESS_TOKEN}
        token: ${{ secrets.PAT_GITHUB_TOKEN }}
        persist-credentials: false
        # alternative: SSH key
        # ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
    - uses: actions/checkout@v4
      with:
        path: 'target'
        repository: '${{ env.target }}'
        token: ${{ secrets.PAT_GITHUB_TOKEN }}
        # fetch all commits
        fetch-depth: 0
        fetch-tags: false
        persist-credentials: false

    - name: Split Repo
      working-directory: .
      run: |
        # [Script]

        echo '::group::Install "git-filter-repo"'
        sudo apt-get update
        sudo apt-get install -y \
          git-filter-repo
        echo '::endgroup::'

        echo '::group::Versions(s)'
        git --version
        git-filter-repo --version
        echo '::endgroup::'

        echo '::group::Git Config'
        git config --global user.name ${{ env.commit_author_name }} || echo user.name failed
        git config --global user.email ${{ env.commit_author_email }} || echo user.mail failed
        git config --global --unset credential.helper || echo credential.helper failed
        git -C ./origin config --unset credential.helper || echo origin local credential.helper failed
        git -C ./target config --unset credential.helper || echo target local credential.helper failed
        echo '::endgroup::'

        echo '::group::Git Remote(s) [Before]'
        git -C ./origin remote -v || echo origin remote -v failed
        git -C ./target remote -v || echo target remote -v failed
        echo '::endgroup::'

        echo '::group::Extract "--path [..]" Parameters from Inputs'
        declare -ra pathsArray=${{ env.paths }}
        declare -a pathArguments=()
        for relativePath in ${pathsArray[@]}; do
          pathArguments+=( "--path" "${relativePath}" )
        done
        echo '::endgroup::'

        echo '::group::Extract "--path-glob [..]" Parameters from Inputs'
        declare -ra pathGlobsArray=${{ env.path_globs }}
        declare -a pathGlobArguments=()
        for pathGlob in ${pathGlobsArray[@]}; do
          pathGlobArguments+=( "--path" "${pathGlob}" )
        done
        echo '::endgroup::'

        echo '::group::Extract "--path-rename [..]" Parameters from Inputs'
        declare -ra renameArray=${{ env.rename }}
        declare -a pathRenameArguments=()
        for rename in ${renameArray[@]}; do
          pathRenameArguments+=( "--path-rename" "${rename}" )
        done
        echo '::endgroup::'

        echo '::group::debug: "--path(-*) [..]" Parameters'
        echo "# of Path Arguments: ${#pathArguments[@]}"
        printf '%s\n' "${pathArguments[@]}"
        echo "# of Path Glob Arguments: ${#pathGlobArguments[@]}"
        printf '%s\n' "${pathGlobArguments[@]}"
        echo "# of Path Rename Arguments: ${#pathRenameArguments[@]}"
        printf '%s\n' "${pathRenameArguments[@]}"
        echo '::endgroup::'

        # see: https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html
        echo '::group::Run "git-filter-repo"'
        git filter-repo \
          --refs ${{ env.ref }} \
          "${pathArguments[@]}" \
          "${pathGlobArguments[@]}" \
          "${pathRenameArguments[@]}" \
          --name-callback \
            'return b"${{ env.commit_author_name }}"' \
          --email-callback \
            'return b"${{ env.commit_author_email }}"' \
          --commit-callback \
            'commit.message += f"\noriginal-commit: https://github.com/${{ env.origin }}/commit/{commit.original_id.decode()}/".encode("ascii")' \
          --source ./origin \
          --target ./target
        echo '::endgroup::'

        echo '::group::Git Branch'
        git -C ./target branch -va
        echo '::endgroup::'

        echo '::group::Git Log'
        git -C ./target log --oneline
        echo '::endgroup::'

        echo '::group::Git Remote(s) [After]'
        git -C ./origin remote -v || echo origin remote -v failed
        git -C ./target remote -v || echo target remote -v failed
        echo '::endgroup::'

        echo '::group::Fix "could not read Username for https://github.com: No such device or address"'
        git config --global url.https://${{ secrets.PAT_GITHUB_TOKEN }}@github.com/.insteadOf https://github.com/
        echo '::endgroup::'
    - name: Push changes
      uses: ad-m/github-push-action@master
      with:
        directory: 'target'
        repository: ${{ env.target }}
        branch: ${{ env.ref }}
        tags: false
        force: false
        force_with_lease: true
        PAT_GITHUB_TOKEN: ${{ secrets.PAT_GITHUB_TOKEN }}
        ssh: false

Quick Reference

Anatomy of a Workflow

name: 'Hello World Workflow'
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: 'Checkout code'
      uses: actions/checkout@v4

    - name: 'Run Hello World Action'
      uses: ./ # Reference the action in the current repository

Frequently Used Events

• push
• pull_request
• schedule
• workflow_dispatch
• repository_dispatch
• issue_comment
• pull_request_review
• pull_request_review_comment
• issues
• release

Log Groups

• echo "::group::Collapsible Group"
• echo "::endgroup::"

Context Reference

github

env

job

jobs

steps

runner

secrets

strategy

matrix

needs

inputs

We hope you enjoyed our comprehensive guide on GitHub Actions. By now, you should have a complete understanding of how complex tasks can be automated using this powerful tool.

For more tips, tutorials, and guides, be sure to sign up for our newsletter below and follow Tower on Twitter and LinkedIn!