CI/CD Setup Guide

This guide walks you through setting up the complete CI/CD pipeline for the Healthy-Stellar contracts repository.

Prerequisites

Repository admin access
Stellar testnet and/or mainnet account with XLM for deployments
Basic understanding of GitHub Actions

Secrets Reference

Which secret does which workflow use? Use this table as the authoritative reference. If the table and any other section of this document disagree, the table wins — and please open a PR to fix the discrepancy.

Secret Name	Workflow(s)	Purpose
`STELLAR_SECRET_KEY`	`deploy-testnet.yml`	Raw secret key (`S...`) imported as the `deployer` identity for testnet deployments
`TESTNET_DEPLOYER_IDENTITY`	`extend-ttls.yml`	Stellar identity credential used by the `stellar` CLI to extend contract TTLs on testnet
`MAINNET_DEPLOYER_IDENTITY`	`extend-ttls.yml`	Stellar identity credential used by the `stellar` CLI to extend contract TTLs on mainnet

ci.yml requires no secrets — it only runs cargo fmt, cargo clippy, cargo test, and a WASM build.

Step 1: Configure Repository Secrets

Navigate to your repository on GitHub
Go to Settings → Secrets and variables → Actions
Click New repository secret
Add each secret described below

`STELLAR_SECRET_KEY`

Name: STELLAR_SECRET_KEY
Value: Your Stellar testnet secret key (starts with S...)
Used by: deploy-testnet.yml
Purpose: Imported as the deployer identity that signs testnet contract deployments

How to create a testnet deployer account:

# Install the Stellar CLI
cargo install --locked stellar-cli --features opt

# Generate a new identity (writes keys to ~/.config/stellar/identity/)
stellar keys generate deployer --network testnet

# Show the secret key to copy into the GitHub secret
stellar keys show deployer

# Get the public address (to fund the account)
stellar keys address deployer

Then fund the account at the Stellar Laboratory Friendbot by pasting the public address.

⚠️ Security: Never commit secret keys to the repository or share them publicly. Rotate them if they are ever exposed.

`TESTNET_DEPLOYER_IDENTITY`

Name: TESTNET_DEPLOYER_IDENTITY
Used by: extend-ttls.yml
Purpose: Passed directly to extend-ttls.sh as the --identity argument and exported as STELLAR_IDENTITY so the stellar CLI can sign TTL-extension transactions on testnet

How to obtain the value:

# After generating your testnet identity (see above), export it
stellar keys show deployer
# Copy the output — this is the value for TESTNET_DEPLOYER_IDENTITY

`MAINNET_DEPLOYER_IDENTITY`

Name: MAINNET_DEPLOYER_IDENTITY
Used by: extend-ttls.yml (scheduled runs and manual mainnet triggers)
Purpose: Passed to extend-ttls.sh and exported as STELLAR_IDENTITY so the stellar CLI can sign TTL-extension transactions on mainnet

How to obtain the value:

# Generate a separate mainnet identity — never reuse testnet keys on mainnet
stellar keys generate mainnet-deployer

# Show the secret key for the GitHub secret value
stellar keys show mainnet-deployer

# Get the address to fund with real XLM
stellar keys address mainnet-deployer

⚠️ Mainnet keys carry real financial risk. Use a dedicated account with the minimum XLM needed for TTL extensions. Rotate this secret immediately if it is ever exposed.

Step 2: Enable GitHub Actions

Go to Settings → Actions → General
Under "Actions permissions", select:
- ✅ Allow all actions and reusable workflows
Under "Workflow permissions", select:
- ✅ Read and write permissions
- ✅ Allow GitHub Actions to create and approve pull requests
Click Save

Step 3: Configure Branch Protection Rules

Protect the main branch to enforce CI requirements:

Go to Settings → Branches
Click Add rule (or edit existing rule for main)
Configure the following:

Branch name pattern

main

Protect matching branches

Require a pull request before merging

✅ Enable
Required approvals: 1
✅ Dismiss stale pull request approvals when new commits are pushed
✅ Require review from Code Owners (if you have a CODEOWNERS file)

Require status checks to pass before merging

✅ Enable
✅ Require branches to be up to date before merging
Required status checks (these are the job names defined in ci.yml):
- CI Success
- Format Check
- Clippy Lint
- Test Suite
- Build WASM

Require conversation resolution before merging

✅ Enable

Require signed commits

⬜ Optional (recommended for enhanced security)

Require linear history

✅ Enable (keeps git history clean)

Do not allow bypassing the above settings

✅ Enable (even for administrators)

Click Create or Save changes

Step 4: Verify Workflows

Test CI Workflow (`ci.yml`)

The CI workflow runs on every push and pull request to main. It has four jobs — Format Check, Clippy Lint, Test Suite, and Build WASM — plus a gating CI Success job. No secrets are required.

Create a test branch:

git checkout -b test-ci

Make a small change (e.g., add a comment to a source file)
Commit and push:

git add .
git commit -m "test: trigger CI workflow"
git push origin test-ci

Open a pull request on GitHub and confirm all five checks turn green.

Test Deployment Workflow (`deploy-testnet.yml`)

This workflow triggers automatically on push to main and can also be triggered manually. It requires the STELLAR_SECRET_KEY secret.

The workflow:

Detects which contracts changed (or uses your manual input)
Builds each contract to WASM
Runs stellar contract optimize on the WASM
Runs stellar contract deploy using the deployer identity imported from STELLAR_SECRET_KEY

To trigger manually:

Go to Actions tab → Deploy to Testnet
Click Run workflow
Optionally specify a comma-separated list of contract names (leave blank to deploy all changed contracts)
Verify the deployment summary in the workflow run output

Test TTL Extension Workflow (`extend-ttls.yml`)

This workflow runs on a schedule (every Monday) and can be triggered manually. It uses the stellar CLI (not soroban) and requires MAINNET_DEPLOYER_IDENTITY and/or TESTNET_DEPLOYER_IDENTITY.

To test with a dry run:

Go to Actions tab → Extend Contract TTLs
Click Run workflow
Set Network to testnet
Set Dry run to true
Verify the workflow completes without errors

Test Security Audit

Go to Actions tab → Security Audit
Click Run workflow → Run workflow
Verify the audit completes successfully
Check for any security issues in the summary

Step 5: Configure Notifications (Optional)

Email Notifications

GitHub automatically sends email notifications for failed workflow runs, security issues, and pull request reviews. Configure in Settings → Notifications.

Slack Integration (Optional)

Create a Slack Incoming Webhook for your workspace and copy the URL.
Add it as a repository secret:
- Name: SLACK_WEBHOOK_URL
- Value: Your webhook URL
Add a notification step to any workflow:

- name: Notify Slack on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
    payload: |
      {
        "text": "CI Failed for ${{ github.repository }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "❌ *CI Failed*\n*Repository:* ${{ github.repository }}\n*Branch:* ${{ github.ref }}\n*Commit:* ${{ github.sha }}"
            }
          }
        ]
      }

Step 6: Set Up Dependabot (Optional but Recommended)

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "cargo"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    labels:
      - "dependencies"
      - "rust"
    commit-message:
      prefix: "chore"
      include: "scope"

Then commit and push:

git add .github/dependabot.yml
git commit -m "chore: add Dependabot configuration"
git push

Step 7: Monitor and Maintain

Weekly Tasks

Review Security Audit Results — check Actions → Security Audit, review any created issues, and update vulnerable dependencies.
Review Dependabot PRs — check changelogs and merge after CI passes.

Monthly Tasks

Review Deployment History — check deployment artifacts, verify contract IDs are documented, and clean up old artifacts if needed.
Update Workflows — check for GitHub Actions version updates, update Rust and stellar-cli versions as needed, and review caching strategies.

Quarterly Tasks

Security Review — run a comprehensive security audit, review all dependencies, and update security policies.
Performance Review — analyze CI run times, optimize slow jobs, and review caching effectiveness.

Troubleshooting

CI Fails on First Run

Problem: CI fails with "required checks not found"

Solution:

Let the CI run complete at least once so the job names are registered
Then add the checks to branch protection
Status checks must exist before GitHub allows them to be required

Deployment Fails with "Secret not found" or "identity not found"

Problem: deploy-testnet.yml exits with an error about the deployer identity or missing secret

Solution:

Confirm STELLAR_SECRET_KEY is added under Settings → Secrets and variables → Actions
Check the secret name is exactly STELLAR_SECRET_KEY (case-sensitive)
Confirm the value starts with S (Stellar secret key format)
The workflow imports this key with stellar keys add deployer --secret-key "$STELLAR_SECRET_KEY" — if the key is malformed, that step will fail

TTL Extension Fails with "identity not found" or Permission Error

Problem: extend-ttls.yml exits with an error about the deployer identity

Solution:

Confirm both MAINNET_DEPLOYER_IDENTITY and TESTNET_DEPLOYER_IDENTITY are configured in repository secrets
Verify neither value is empty — an empty identity will silently fail or produce a cryptic CLI error
Check that the identity's account has enough XLM to cover the transaction fees on the target network

Security Audit Creates Too Many Issues

Problem: Multiple security issues created for the same vulnerabilities

Solution:

The workflow checks for existing issues before creating new ones
If duplicates occur, manually close the extras
Open a PR to improve the deduplication logic in the workflow

WASM Build Fails

Problem: Contracts don't compile to WASM

Solution:

Test locally: cargo build --release --target wasm32-unknown-unknown
Check for platform-specific dependencies
Ensure all contracts use #![no_std]
Review soroban-sdk compatibility

Deployment Takes Too Long

Problem: Deployment workflow times out

Solution:

The workflow only deploys changed contracts automatically — verify the change detection is working
Use the manual trigger to deploy specific contracts by name
Optimize WASM binaries before deployment
Consider parallel deployment for large contract sets

Advanced Configuration

Custom Deployment Environments

Create a separate workflow for mainnet releases:

# .github/workflows/deploy-mainnet.yml
name: Deploy to Mainnet

on:
  release:
    types: [published]

env:
  STELLAR_NETWORK_PASSPHRASE: "Public Global Stellar Network ; September 2015"
  STELLAR_RPC_URL: "https://soroban-mainnet.stellar.org"

# ... rest of deployment workflow
# Use secrets.MAINNET_DEPLOYER_IDENTITY, not STELLAR_SECRET_KEY

Matrix Testing

Test across multiple Rust versions:

test:
  strategy:
    matrix:
      rust: [stable, beta, nightly]
  steps:
    - uses: dtolnay/rust-toolchain@master
      with:
        toolchain: ${{ matrix.rust }}
    - run: cargo test --workspace

Conditional Workflows

Run workflows only when contract files change:

on:
  push:
    paths:
      - 'contracts/**'
      - 'Cargo.toml'
      - 'Cargo.lock'

Best Practices

Test locally first — run all CI checks locally before pushing. See .github/workflows/README.md for the exact commands.
Keep secrets secure — never commit secrets, rotate them regularly, and use separate accounts for testnet and mainnet.
Use the Secrets Reference table — when adding a new workflow that needs credentials, update the table at the top of this document at the same time.
Monitor CI performance — review workflow run times, optimize caching, and parallelize where possible.
Stay updated — keep GitHub Actions versions, Rust, and stellar-cli current and review security advisories weekly.
Document changes — update this file and the workflow README whenever secrets or CLI commands change.

Getting Help

GitHub Actions Issues: GitHub Community Forum
Stellar CLI Issues: Stellar Discord
Security Issues: Create a private security advisory in the repository

Setup Checklist

Use this checklist to verify your setup is complete:

Next Steps

After completing this setup:

Create a test PR to verify all CI checks pass
Trigger a manual testnet deployment to verify STELLAR_SECRET_KEY is working
Run a dry-run TTL extension to verify TESTNET_DEPLOYER_IDENTITY is working
Review the security audit results
Train team members on the CI/CD process and point them to the Secrets Reference table first

FilesExpand file tree

CICD_SETUP.md

Latest commit

History

CICD_SETUP.md

File metadata and controls

CI/CD Setup Guide

Prerequisites

Secrets Reference

Step 1: Configure Repository Secrets

STELLAR_SECRET_KEY

TESTNET_DEPLOYER_IDENTITY

MAINNET_DEPLOYER_IDENTITY

Step 2: Enable GitHub Actions

Step 3: Configure Branch Protection Rules

Branch name pattern

Protect matching branches

Require a pull request before merging

Require status checks to pass before merging

Require conversation resolution before merging

Require signed commits

Require linear history

Do not allow bypassing the above settings

Step 4: Verify Workflows

Test CI Workflow (ci.yml)

Test Deployment Workflow (deploy-testnet.yml)

Test TTL Extension Workflow (extend-ttls.yml)

Test Security Audit

Step 5: Configure Notifications (Optional)

Email Notifications

Slack Integration (Optional)

Step 6: Set Up Dependabot (Optional but Recommended)

Step 7: Monitor and Maintain

Weekly Tasks

Monthly Tasks

Quarterly Tasks

Troubleshooting

CI Fails on First Run

Deployment Fails with "Secret not found" or "identity not found"

TTL Extension Fails with "identity not found" or Permission Error

Security Audit Creates Too Many Issues

WASM Build Fails

Deployment Takes Too Long

Advanced Configuration

Custom Deployment Environments

Matrix Testing

Conditional Workflows

Best Practices

Getting Help

Setup Checklist

Next Steps

`STELLAR_SECRET_KEY`

`TESTNET_DEPLOYER_IDENTITY`

`MAINNET_DEPLOYER_IDENTITY`

Test CI Workflow (`ci.yml`)

Test Deployment Workflow (`deploy-testnet.yml`)

Test TTL Extension Workflow (`extend-ttls.yml`)