Setup Git Access Token¶

See the GitHub docs for Personal Access Token (Classic).

• The minimum required scope is repo

See the GitHub docs for Fine-grained tokens.

• Repository access
  • Set to Public Repositories (read-only) for only public repositories.
  • Set to All Repositories for all repositories.
• The minimum required permissions are:
  • Contents -> Read-only
  • Metadata -> Read-only

GitHub Apps are supported natively in Doco-CD.

See the GitHub docs for registering a GitHub Apps.

• The minimum required permissions are:
  • Repository contents -> Read-only
  • Repository metadata -> Read-only

The sample docker-compose.yml already reads GIT_ACCESS_TOKEN from the environment. Save the token in a .env file next to the Compose file of Doco-CD:

GIT_ACCESS_TOKEN=your_read_only_token

Run chmod 600 .env so other users of the host cannot read it. Then start or recreate Doco-CD with docker compose up -d.

Doco-CD reads the token from a file if you set GIT_ACCESS_TOKEN_FILE. This keeps the token out of the container's environment. Save the token in a file that only root can read, then mount it as a Docker secret:

sudo mkdir -p /opt/doco-cd
echo 'your_read_only_token' > /opt/doco-cd/git-access-token
sudo chmod 600 /opt/doco-cd/git-access-token

services:
  app:
    environment:
      GIT_ACCESS_TOKEN_FILE: /run/secrets/git_access_token
    secrets:
      - git_access_token

secrets:
  git_access_token:
    file: /opt/doco-cd/git-access-token

Use either GIT_ACCESS_TOKEN or GIT_ACCESS_TOKEN_FILE, not both.

The repository contains only the path of a token file on the Docker host, never the token itself. Save the token in a file that only root can read:

sudo mkdir -p /opt/doco-cd
echo 'your_read_only_token' > /opt/doco-cd/git-access-token
sudo chmod 600 /opt/doco-cd/git-access-token

Reference the file in the Compose file of Doco-CD in your repository:

services:
  doco-cd:
    environment:
      GIT_ACCESS_TOKEN_FILE: /run/secrets/git_access_token
    secrets:
      - git_access_token

secrets:
  git_access_token:
    file: /opt/doco-cd/git-access-token # Path on the Docker host

The example's compose.yaml already has these lines as comments. Push the change, then run the bootstrap with the token:

export GIT_ACCESS_TOKEN="$(sudo cat /opt/doco-cd/git-access-token)"
./bootstrap.sh

The repository contains the token as a SOPS-encrypted file. The age key that decrypts it stays on the Docker host. This way, one key on the host protects the token and any other secret you keep in Git.

1. Create an age key on the Docker host. The command prints the public key. Note it.

   sudo mkdir -p /opt/doco-cd
   sudo age-keygen -o /opt/doco-cd/sops_age_key.txt
   

2. On your own computer, encrypt the token with the public key and add the result to your repository. Use the file extension .txt so that SOPS treats the file as plain text.

   echo 'your_read_only_token' > git-access-token.txt
   sops encrypt --age <age_public_key> git-access-token.txt > doco-cd/git-access-token.enc.txt
   rm git-access-token.txt
   

3. Reference both files in the Compose file of Doco-CD in your repository:

   doco-cd/compose.yaml

   services:
     doco-cd:
       environment:
         GIT_ACCESS_TOKEN_FILE: /run/secrets/git_access_token
         SOPS_AGE_KEY_FILE: /run/secrets/sops_age_key
       secrets:
         - git_access_token
         - sops_age_key
   
   secrets:
     git_access_token:
       file: ./git-access-token.enc.txt # Encrypted file in your repository
     sops_age_key:
       file: /opt/doco-cd/sops_age_key.txt # Path on the Docker host
   

   Doco-CD decrypts the file in its own copy of the repository before it starts the container. The container reads the plain token, and your repository keeps only the encrypted file.

4. Add the age key to the docker run command in bootstrap.sh, so that the bootstrap can decrypt the file as well:

   bootstrap.sh

     -e SOPS_AGE_KEY="${SOPS_AGE_KEY:-}" \
   

5. Push your changes, then run the bootstrap with the token and the age key:

   export GIT_ACCESS_TOKEN=<your_git_access_token>
   export SOPS_AGE_KEY="$(sudo cat /opt/doco-cd/sops_age_key.txt)"
   ./bootstrap.sh
   

   If Docker needs sudo on your host, run sudo --preserve-env=GIT_ACCESS_TOKEN,SOPS_AGE_KEY ./bootstrap.sh instead.

The repository contains only a reference to the token in an external secret provider. Doco-CD fetches the token during each deployment of its own Compose file. You still need to give Doco-CD the access token of the provider, for example from a file on the Docker host. This example uses Bitwarden Secrets Manager. The settings for other providers are on their own pages.

Reference the token in the deployment configuration of Doco-CD:

name: doco-cd
working_dir: doco-cd
compose_files: [compose.yaml]
timeout: 120
external_secrets:
  GIT_ACCESS_TOKEN: 138e3a97-ed58-431c-b366-b35500663411 # ID of the secret in your provider

Use the variable in the Compose file of Doco-CD:

services:
  doco-cd:
    environment:
      GIT_ACCESS_TOKEN: ${GIT_ACCESS_TOKEN}
      SECRET_PROVIDER: bitwarden_sm
      SECRET_PROVIDER_ACCESS_TOKEN_FILE: /run/secrets/secret_provider_access_token
    secrets:
      - secret_provider_access_token

secrets:
  secret_provider_access_token:
    file: /opt/doco-cd/secret-provider-access-token # Path on the Docker host

The bootstrap needs the provider settings and the token to clone the repository. Add the provider settings to the docker run command in bootstrap.sh:

  -e SECRET_PROVIDER=bitwarden_sm \
  -e SECRET_PROVIDER_ACCESS_TOKEN="${SECRET_PROVIDER_ACCESS_TOKEN:-}" \

Then run the bootstrap:

export GIT_ACCESS_TOKEN=<your_git_access_token>
export SECRET_PROVIDER_ACCESS_TOKEN="$(sudo cat /opt/doco-cd/secret-provider-access-token)"
./bootstrap.sh