# Push Agent Changes to a Repository Branch (https://www.shipfox.io/docs/how-to/author-workflows/push-repository-changes)

Description: Grant one job authenticated Git write access, check an agent's README change, and push it to a new branch.

Use this guide when an agent must edit the project repository and a later shell
step must push the checked change. It grants Git write access without granting
any integration tool.

## Before you begin [#before-you-begin]

You need:

* The workflow repository must use an integration connection for GitHub that
  can write repository contents.
* A repository with `README.md`.
* A repository where a temporary `shipfox/docs-*` branch is safe.

## Add the workflow [#add-the-workflow]

Create `.shipfox/workflows/push-readme-update.yml`. This is a complete
workflow:

```yaml
# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Push a README update
runner: shipfox

triggers:
  manual:
    source: manual

jobs:
  update:
    checkout:
      permissions:
        contents: write
    steps:
      - prompt: |
          Improve one unclear setup instruction in README.md.
          Change no other file. Do not commit or push.

      - run: git diff --check

      - env:
          BRANCH_NAME: "shipfox/docs-${{ run.id }}"
        run: |
          git switch -c "$BRANCH_NAME"
          git add README.md
          if git diff --cached --quiet; then
            echo "README.md did not change." >&2
            exit 1
          fi
          git commit -m "Improve README setup instructions"
          git push -u origin "$BRANCH_NAME"
```

Checkout permission applies to the whole job because the edit and push share
one checkout. The prompt forbids the earlier agent step from pushing. The shell
step owns the intended commit and push.

Commit and push the workflow file to the project's default branch. Wait for
**Push a README update** to sync.

## Verify the branch [#verify-the-branch]

Start the workflow from the **Workflows** tab.

1. Confirm that the agent changes only `README.md`.
2. Confirm that `git diff --check` passes before the push step.
3. Open GitHub and confirm that a `shipfox/docs-<run-id>` branch contains one
   commit with the README change.
4. Confirm that the agent step has no `integrations` selection.

The checkout credential remains available to later steps by default. Set
`persist-credentials: false` only when no later step should perform an
authenticated Git command. See [Checkout
fields](https://www.shipfox.io/docs/reference/workflow-schema#checkout-fields).

Verified managed runner images renew persisted Git credentials during long jobs.
An older self-hosted runner uses static credentials. The job shows an upgrade
warning. Update that runner image when the workflow needs Git access beyond the
credential lifetime.

Git commands inside a container started by a user step do not receive the host
runner's credential helper or Unix socket. Supply a credential explicitly to
that container when it needs authenticated Git access.