Install a workflow on GitHub Actions running Claude Code

Each run is a job on a new GitHub hosted virtual machine. The workflow file's own steps run as code, and a step that uses anthropics/claude-code-action runs Claude Code for the steps an AI decides. The job sees the checked out repository and every secret it is handed, and so does Claude.

Run awml fit with the workflow's security view and this description first. GitHub runs the machine and sees what the job handles, which the fit does not check, so make sure every scope the job touches allows GitHub.

What to create

1. A repository holding the workflow's scripts, its instructions in CLAUDE.md or a skill under .claude/skills/, and its contexts under notes if they are kept there.
2. The Claude GitHub App on the repository: run /install-github-app in Claude Code, or follow the manual setup.
3. A workflow file at .github/workflows/<workflow>.yml. Each code step is a run: step. Each AI step is a step using anthropics/claude-code-action@v1 with a prompt, which names the step, what it reads, what it writes and what its operation must not do, and claude_args giving --allowedTools for exactly the tools it needs. An outside action marked Ask ends in a draft, an issue or a draft pull request for a person to approve, never in the action itself. A final step commits and pushes changed notes if the workflow writes them, which needs contents: write in the job's permissions.

name: <workflow>
on:
  schedule:
    - cron: "7 7 * * 1-5"
      timezone: "Europe/London"
  workflow_dispatch:
jobs:
  run:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v5
      - run: ./scripts/bring-in.sh
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Use the <workflow> skill for this run."
          claude_args: |
            --allowedTools "Read,Edit,Bash(./scripts/*)"

Where secrets go

Put the Claude API key in a repository secret named ANTHROPIC_API_KEY, or a subscription token from claude setup-token in CLAUDE_CODE_OAUTH_TOKEN. Run gh secret set ANTHROPIC_API_KEY and paste the value at its prompt, so it stays out of your shell history. Keys for other services go in repository secrets the same way, handed only to the steps that need them. Never commit a key to the repository.

How to schedule the triggers

Add a schedule with a cron expression under on. It runs in UTC unless you give a timezone, no more often than every five minutes, and only from the default branch. Scheduled runs can be late at busy times, most of all on the hour, so choose minutes past it. In a public repository, schedules stop after 60 days without activity. workflow_dispatch lets you run it by hand; repository_dispatch lets another service start it.

How to check it is running

gh run list --workflow <workflow>.yml lists recent runs and gh run view <run id> --log shows a run's log. gh workflow run <workflow>.yml starts one now, through workflow_dispatch. The repository's Actions tab shows the same. GitHub sends a scheduled workflow's notifications to the person who last changed its cron expression.

Sources

• https://code.claude.com/docs/en/github-actions
• https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule
• https://docs.github.com/en/actions/concepts/runners/github-hosted-runners
• https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets