GitHub Files and Templates

Use these actions to write repository content.

Use github.template.apply when several files share the same values and commit message. Use github.file.create when one file needs a separate message, a separate source, or special handling.

Repository template values

When an action receives owner and repo, Forge adds repository-aware template values automatically:

Value	Example
gitHost	github.com
gitVendor	github
repositoryOwner	adaptive-labs
repositoryName	payments-api
repositoryFullName	adaptive-labs/payments-api
repositoryQualifiedOwner	github.com/adaptive-labs
modulePath	github.com/adaptive-labs/payments-api

This keeps molds portable. Prefer these built-in values over hardcoding module paths.

github.template.apply

Applies a directory of templates from the mold repository into the target repository.

steps:
  - id: apply-service-template
    name: Apply service template
    action: github.template.apply
    inputs:
      owner: "${{ inputs.owner }}"
      repo: "${{ inputs.name }}"
      source_path: ./skeleton
      target_path: .
      message: "feat: scaffold service"
      template_values:
        serviceName: "${{ inputs.name }}"
        description: "${{ inputs.description }}"
        port: "${{ inputs.port }}"
        goVersion: "${{ inputs.goVersion }}"

Inputs:

Input	Required	Description
owner	Yes	Repository owner or qualified owner
repo	Yes	Target repository name
source_path	Yes	Template directory relative to the mold file
target_path	No	Destination directory in the repository
message	No	Commit message used for written files
template_values	No	Values available inside the templates
include	No	Only include matching files
exclude	No	Skip matching files

Files ending in .tmpl are rendered with Go template syntax and written without the .tmpl suffix. For example, skeleton/cmd/{{ .serviceName }}/main.go.tmpl becomes cmd/payments-api/main.go.

The template directory must stay inside the mold directory. This prevents a mold from reading unrelated repository files.

Example with include and exclude filters:

steps:
  - id: apply-template
    name: Apply template
    action: github.template.apply
    inputs:
      owner: "${{ inputs.owner }}"
      repo: "${{ inputs.name }}"
      source_path: ./skeleton
      include:
        - "cmd/**"
        - "internal/**"
        - go.mod.tmpl
      exclude:
        - "**/*.bak"
      template_values:
        serviceName: "${{ inputs.name }}"

github.file.create

Creates or updates one file.

Inline content:

steps:
  - id: add-readme
    name: Add README
    action: github.file.create
    inputs:
      owner: "${{ inputs.owner }}"
      repo: "${{ inputs.name }}"
      path: README.md
      message: "docs: add README"
      content: |
        # ${{ inputs.name }}

        ${{ inputs.description }}

Template file from the same mold directory:

steps:
  - id: add-main
    name: Add main package
    action: github.file.create
    inputs:
      owner: "${{ inputs.owner }}"
      repo: "${{ inputs.name }}"
      path: "cmd/${{ inputs.name }}/main.go"
      message: "feat: add main package"
      template_path: ./skeleton/cmd/main.go.tmpl
      template_values:
        serviceName: "${{ inputs.name }}"
        port: "${{ inputs.port }}"

Template file from a template store:

steps:
  - id: add-dockerfile
    name: Add Dockerfile
    action: github.file.create
    inputs:
      owner: "${{ inputs.owner }}"
      repo: "${{ inputs.name }}"
      path: Dockerfile
      message: "build: add Dockerfile"
      template_url: "https://raw.githubusercontent.com/shoehorn-dev/shoehorn-molds-templates/main/go-service/Dockerfile.tmpl"
      template_values:
        serviceName: "${{ inputs.name }}"

Inputs:

Input	Required	Description
owner	Yes	Repository owner or qualified owner
repo	Yes	Target repository name
path	Yes	Path to write in the repository
message	No	Commit message
content	One content source is required	Inline file content
template_path	One content source is required	Template path relative to the mold file
template_url	One content source is required	Remote template URL
template_values	No	Values available inside templates
branch	No	Branch to write to

Remote templates can be raw HTTP URLs or GitHub template URLs. Prefer a stable branch, tag, or commit SHA for shared template stores.