# Sync to GitHub Actions

seekrit can push a whole environment into GitHub Actions secrets — at repository, deployment
environment, or organization scope — so a workflow reads them with the ordinary
`${{ secrets.NAME }}` syntax and no seekrit-specific code. For most workflows the published
`seekritdev/github-action` is a better fit than syncing: it resolves and decrypts inside your
workflow run, so nothing is copied to GitHub and a rotated value needs no re-sync.

> **Warning:** **Read this before setting one up: you probably want the Action instead.**
> 
> GitHub Actions is a runtime seekrit *can* reach into, which makes it the one
>   destination here where a strictly better option already exists. The published
>   [`seekritdev/github-action`](https://github.com/seekritdev/github-action)
>   resolves and decrypts **inside your workflow run**:
> 
> ```yaml
>   - uses: seekritdev/github-action@v1
>     with:
>       token: ${{ secrets.SEEKRIT_TOKEN }}
>       app: storefront
>       env: production
>   ```
> 
> Nothing is copied to GitHub, nothing is stored there, a rotated value is picked
>   up on the next run with no re-sync, and seekrit's servers never decrypt
>   anything. Syncing gives all three of those up.
> 
> Sync is the right answer only where the Action cannot reach — see
>   [when to sync anyway](#when-to-sync-anyway) below.

| At a glance | |
| --- | --- |
| **What seekrit writes** | Actions secrets, at repository, deployment environment, or organization scope |
| **Addressed by** | `owner/repo`, plus an environment name — or an organization login and a visibility |
| **Connection carries** | The token, and a base URL for GitHub Enterprise Server only |
| **Token permission** | Fine-grained **Secrets** repository permission (write), or the organization **Secrets** permission |
| **Takes effect** | Next workflow run |
| **Value visibility** | Write-only — GitHub never discloses a secret value again |

## When to sync anyway

GitHub resolves some things before any step of yours could run, so no Action can
supply them. Those are the cases this connector is for:

- **A third-party action that takes a credential as a `with:` input** — the value
  is interpolated from the `secrets` context when the step is created.
- **`secrets: inherit`** into a reusable workflow, which passes the calling
  workflow's `secrets` context wholesale.
- **Job-level `container:` and `services:` credentials**, resolved before the
  job's first step.
- **Dependabot and Codespaces**, which read their own secret stores and run no
  workflow you control. (Those are separate GitHub APIs; this connector writes
  Actions secrets only.)

If your situation is not one of these, use the Action.

## 1. Create a token

Prefer a **fine-grained** personal access token with the **Secrets** repository
permission set to *Read and write*, scoped to only the repositories this
connection syncs. For organization secrets, it needs the organization **Secrets**
permission instead.

A classic token needs `repo` — or `admin:org` for organization secrets — which
grants vastly more than writing secrets. Use fine-grained where you can.

```bash
printf '%s' "$GITHUB_TOKEN" \
  | seekrit sync connect --name acme-github --provider github-actions
```

A github.com connection has no second half to state: a GitHub token addresses
everything by `owner/repo` or `org`, and those are the binding's business. For a
self-hosted **GitHub Enterprise Server** appliance, add `--base-url
https://github.acme.com/api/v3`. Leave it off for github.com and for Enterprise
Cloud. It must be `https` — that URL carries the token.

## 2. Bind an environment

GitHub has three secret scopes, and a binding picks one. They are three different
endpoints with three different blast radii — and each has its **own** encryption
key, so a value sealed for one cannot be written to another.

### A repository's secrets

Readable by every workflow in it, including one added by a pull request from a
collaborator with write access. That is GitHub's model, not seekrit's — and it is
the reason to prefer the environment scope for anything touching production.

```bash
seekrit sync verify acme-github --provider github-actions \
  --gh-repo acme/storefront

seekrit sync enable --connection acme-github --provider github-actions \
  --gh-repo acme/storefront \
  --app storefront --env production --acknowledge-decryption
```

`--gh-repo` takes the pair as one flag, because that is how GitHub writes a
repository everywhere; asking for it in two invites pasting the pair into one of
them.

### A deployment environment's secrets

The narrowest scope GitHub has, and the one to prefer:

```bash
seekrit sync enable --connection acme-github --provider github-actions \
  --gh-repo acme/storefront --gh-environment production \
  --app storefront --env production --acknowledge-decryption
```

A job reads these only by declaring `environment: production`, which also
subjects it to that environment's protection rules — required reviewers, wait
timers, and the branch policy. That combination is as close as GitHub gets to
"this secret is for production, and reaching it takes an approval".

The environment must already exist. seekrit will not create one: an environment
is a deployment gate, and silently creating an unprotected one because a name was
misspelled would quietly remove the protection you were relying on.

### An organization's secrets

The widest scope in the product, and the only destination on any provider that
can hand a value to repositories nobody named.

```bash
seekrit sync enable --connection acme-github --provider github-actions \
  --gh-org acme --gh-visibility selected --gh-repo-ids 1296269,1296270 \
  --app storefront --env production --acknowledge-decryption
```

> **Warning:** **`--gh-visibility all` hands the value to every repository in the
>   organization** — including ones added tomorrow, and public ones. seekrit
>   deliberately has no default here and defaults the CLI to `private`; state what
>   you mean.
> 
> `selected` takes numeric repository **IDs**, not names, because that is what
>   GitHub's API takes. Get one with `gh api repos/acme/storefront --jq .id`.
>   seekrit does not resolve names to IDs on your behalf: guessing which repository
>   an ambiguous name meant would widen a secret's reach silently. Passing IDs with
>   any other visibility is refused rather than ignored, so a stored binding never
>   contradicts its own behavior.

## How a push behaves

- **The value is encrypted before it leaves seekrit.** GitHub does not accept a
  plaintext secret: each value is sealed to the scope's own X25519 public key as
  a libsodium sealed box, and GitHub decrypts it on receipt.

  One nice consequence: GitHub never sees a plaintext value at all, so it cannot
  echo one back into an error message — the failure reasons stored on a run row
  cannot carry a secret value even in principle. Other connectors scrub responses
  for exactly that reason; here there is nothing to scrub.
- **Each scope has its own key, fetched once per run.** A value sealed for a
  repository cannot be written to that repository's `production` environment, or
  to its organization — the three are different recipients. So a run is one `GET`
  for the key, then one `PUT` per name.
- **A run is capped at 150 operations**, sized against GitHub's *secondary* rate
  limit rather than its primary one: 900 points a minute, where a `GET` costs 1
  and a `PUT` or `DELETE` costs **5**. That is 180 mutating requests a minute,
  well below the 5,000-an-hour primary limit.
- **seekrit cannot detect value drift here, only presence.** Actions secrets are
  write-only: once set, no one can read a value back through the UI, CLI, or API
   — which is what you want for something a secrets manager owns.

Values take effect on the **next workflow run**; a sync run starts nothing.

## Name and value rules

> **Note:** **Secret names are case-insensitive at GitHub**, which no other destination
>   here is. `db_url` and `DB_URL` are one secret, so a name mapping that produces
>   both would write it twice and report both as pushed while one value silently
>   won.
> 
> seekrit detects that before it writes anything and fails **every** name in the
>   collision, naming them — it cannot know which one you meant. Watch for it if the
>   binding folds case. Rename or filter all but one.

> **Note:** GitHub will not accept every name seekrit will. Secret names take only letters,
>   numbers, and underscores, must start with a letter or an underscore, and cannot
>   begin with `GITHUB_`, which GitHub reserves for itself. Values stop at **48
>   KB**, checked against the plaintext — the number you can act on — and before
>   sealing, so an over-size body is never built to be refused. A name that breaks
>   one of those is reported as a failure against that name alone; the rest of the
>   environment still pushes. Watch for it if you use a `--prefix`.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `403` on every name | The token lacks the Secrets permission for that scope, or the fine-grained token doesn't include this repository | Repository, environment, and organization secrets are three permissions — check the one the binding writes |
| `404` on the environment | The deployment environment doesn't exist | Create it in Settings → Environments. seekrit will not create one, because that would silently drop its protection rules |
| `404` on the repository with a valid token | A fine-grained token that does not list this repository | Add it to the token's repository access |
| A whole set of names failed as a collision | Two mapped names differ only by case | GitHub is case-insensitive; rename or filter all but one |
| One name failed, rest landed | The mapped name starts with a digit, begins `GITHUB_`, or the value is over 48 KB | Fix the prefix or rename |
| `422` on an org write | `--gh-visibility selected` with no repository IDs, or IDs given for another visibility | Pass numeric IDs with `selected`, and none otherwise |
| Rate-limited, run reported partial | GitHub's secondary rate limit — mutating calls cost 5 points each | Nothing to do — seekrit backs off and retries the rest |
| A rotated value isn't picked up | Actions read GitHub's copy at run start | The next workflow run has it. Or drop sync and use the Action, which needs no re-sync at all |

## See also

- [`seekritdev/github-action`](https://github.com/seekritdev/github-action) — the option to prefer
- [CI/CD & containers](/docs/guides/ci-cd) — wiring seekrit into pipelines without a copy at the destination
- [Third-party sync](/docs/guides/third-party-sync) — the shared model, naming and filtering, deletions

## Common questions

### Should I sync seekrit secrets to GitHub Actions, or use the seekrit Action?

Prefer the seekritdev/github-action for most workflows: it resolves and decrypts inside the run, so nothing is copied to GitHub, a rotated value needs no re-sync, and seekrit's servers never decrypt anything. Sync is for the handful of cases the Action can't reach — a third-party action's with: input, secrets: inherit into a reusable workflow, job-level container: or services: credentials, or Dependabot and Codespaces.

### Which GitHub Actions secret scope should I sync a production secret to?

Prefer the deployment environment scope over repository scope. A repository secret is readable by every workflow in it, including one added by a pull request from a collaborator with write access; an environment secret is only reachable by a job that declares environment: production, which also subjects it to that environment's protection rules — required reviewers, wait timers, branch policy.

### Does GitHub ever see a plaintext seekrit secret value?

No. Each value is sealed to the target scope's own X25519 public key as a libsodium sealed box before it leaves seekrit, and GitHub decrypts it on receipt. Actions secrets are also write-only afterward — no one can read a value back through the UI, CLI, or API once it's set.

### Why did syncing to GitHub Actions fail for only one secret name?

GitHub secret names take only letters, numbers, and underscores, must start with a letter or underscore, cannot begin with GITHUB_, and values stop at 48 KB. A name that breaks one of those rules fails on its own; the rest of the environment still pushes. Names are also case-insensitive at GitHub, so two mapped names differing only by case fail the whole collision rather than silently overwriting one another.

### When does a rotated secret reach a GitHub Actions workflow after syncing?

On the next workflow run — a sync run starts nothing itself, and Actions reads whatever copy of the secret existed when that run started. If you need rotation to apply with no re-sync step at all, that's the case for the seekritdev/github-action instead of syncing.
