# GitHub access token
URL: https://ship-and-scale.vercel.app/docs/accounts/github
Create a GitHub token and save it for deployment.
By the end of this guide, your GitHub token will be saved in the starter's root `.env` file. Deployment Kickstart uses it to create your app's private repository and publish your source code.
You can do this after your local app works. For downloading the starter, follow [Setup](/docs/start/environment#get-access-to-the-starter); the deployment token isn't needed for your first Kickstart.
## Create and save the token [#create-and-save-the-token]
### Open Fine-grained tokens [#open-fine-grained-tokens]
Sign in to [GitHub](https://github.com/login), or [create an account](https://github.com/signup). Open **Settings → Developer settings → Personal access tokens → Fine-grained tokens**, or go directly to [Fine-grained tokens](https://github.com/settings/personal-access-tokens).
Click **Generate new token**. If GitHub asks you to confirm access, complete its verification to continue.
GitHub · Fine-grained tokens → Generate new token. Existing accounts may show a token list here.
### Choose the owner and repository access [#choose-the-owner-and-repository-access]
Fill in the token form:
1. **Token name:** enter `Ship & Scale deployment`.
2. **Resource owner:** choose the account or organization that will own the app repository. It must match `GITHUB_OWNER`.
3. **Expiration:** choose **90 days**. That covers deployment and retries; Kickstart only uses this token during deployment.
4. **Repository access:** automatic repository creation needs **All repositories**, which also covers every current and future repo under that owner. To limit access to one repository, first create the exact empty private repository in GitHub, then choose **Only select repositories** and select that repository.
Leave **Description** blank unless you want to add a note.
GitHub - choose the account that owns the repo. The example shows All repositories for automatic creation and a 30-day expiry.
**Automatic creation needs broad repository access**
**All repositories** includes every current and future repository under the selected owner. A fine-grained token can select one owner only. For least access, precreate the exact empty private repository and use **Only select repositories**; set `GITHUB_OWNER`, `GITHUB_REPO_NAME` and its numeric `GITHUB_REPO_ID` to that repository before checking deployment.
### Add the repository permissions [#add-the-repository-permissions]
Scroll to **Permissions**. With **Repositories** selected, click **Add permissions**. Search for and select **Administration**, then **Contents**. Close the menu and change each permission's **Access** to **Read and write**.
GitHub · Add permissions → search for a permission → select it. Repeat for Contents.
Your permissions should match this table:
| Permission | Access |
| -------------- | ------------------------------------------------------------- |
| Administration | Read and write (create/manage the repository) |
| Contents | Read and write (publish source) |
| Metadata | Read-only, added automatically |
| Workflows | Read and write only when publishing `.github/workflows` files |
Leave **Account** permissions unchanged. A fine-grained token for an organization may need owner approval before it works.
GitHub · Check the access levels, then click Generate token.
Click **Generate token**, then copy the token immediately. You won't be able to view the full value again after leaving the page.
### Save it in `.env` [#save-it-in-env]
Open the root `.env` file beside `package.json`. If it doesn't exist, copy `.env.example` to `.env`. Find the existing `GITHUB_TOKEN=` line, paste your token after the equals sign and save:
```dotenv title="Your private .env"
GITHUB_TOKEN=replace_with_your_github_token
```
Replace the example value with your token. Keep one active `GITHUB_TOKEN` line and preserve the file's other settings. On Windows, make sure the file is named `.env`, not `.env.txt`.
Keep this token only in your local `.env`. It's a setup credential, so it never goes into Vercel's environment variables either.
## You are finished when [#you-are-finished-when]
* `GITHUB_TOKEN` has one saved value in the root `.env` file.
* For a new automatic deployment, `GITHUB_OWNER`, `GITHUB_REPO_NAME` and `GITHUB_REPO_ID` remain blank. Kickstart fills them in. Keep existing values if you've already started deployment.
Next, prepare your [Vercel token and GitHub App connection](/docs/accounts/vercel). Vercel needs that connection to build from your repository. If you limit the App to selected repositories, add the new repository when Kickstart pauses for authorization, then rerun with the same saved settings.
Once all deployment accounts are ready, run this read-only check:
```sh
npm run kickstart:deploy -- --check
```
Resolve any errors before deploying. This command checks your configuration and account access; it doesn't create a repository or prove that a future push will succeed.
## Use a precreated empty repository [#use-a-precreated-empty-repository]
**Optional: limit the token to one repository**
1. Create a **private** repository in your account. Leave it empty: don't add a README, license, `.gitignore` or initial commit.
2. In the token form, choose **Only select repositories** and select that repository. Use the same permissions listed above.
3. Get its numeric ID. GitHub doesn't show it on the repository page. If you use GitHub CLI, replace the owner and repository in this command:
```sh
gh api repos/YOUR_OWNER/YOUR_REPOSITORY --jq .id
```
Without GitHub CLI, ask your coding agent to read the `id` field from `https://api.github.com/repos/YOUR_OWNER/YOUR_REPOSITORY` using the `GITHUB_TOKEN` in your `.env`, without printing the token.
4. Save your token and these identifiers in `.env`, replacing all example values:
```dotenv
GITHUB_OWNER=your-owner
GITHUB_REPO_NAME=your-empty-repository
GITHUB_REPO_ID=123456789
```
Use the numeric ID returned by GitHub. Kickstart can initialize a matching empty private repository; a populated repository stops setup.
**If the token or repository access doesn't work**
For an expired or invalid token, create a replacement with the same owner and permissions and update only `GITHUB_TOKEN`. Keep your generated repository settings and rerun the deployment check.
For an organization-owned repository, choose that organization as **Resource owner** and set `GITHUB_OWNER` to its name. Organization policies may require approval before the token can access private repositories. See [GitHub's token guide](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
If a push fails after repository creation, fix the access problem and rerun with the saved settings. Keep the `.kickstart` receipt; don't delete repository IDs, force-push or create a replacement repository to bypass the error. If the remote repository has new commits, reconcile them with normal Git tools first.
[Back to Accounts](/docs/accounts)
Continue with Vercel to prepare for deployment.
