Collaborator deployment to Cloudsmith: CircleCI invitation to join your organization

[rgleason]

Step 1: Ensure You Are an Organization Admin

Only organization admins can invite collaborators.

Step 2: Invite Collaborators via Email

1. Log in to CircleCI.
2. Navigate to your organization settings.
3. Find the "People" or "Members" section.
4. Click "Invite Members" or "Add Collaborators."
5. Enter the email addresses of the collaborators you want to invite.
6. Send the invitation.

Step 3: Collaborators Accept the Invitation

1. Collaborators receive an email with an invitation link.
2. They click the link and follow the prompts to join your organization.

Step 4: Collaborators Join via GitHub or Bitbucket (Optional)

1. If your organization is connected to GitHub or Bitbucket, collaborators can join using OAuth by logging into CircleCI with their GitHub or Bitbucket accounts.
2. They can search for your organization on their CircleCI homepage and request to join.

Step 5: Set Permissions and Environment Variables

1. After collaborators join, ensure they have the appropriate permissions.
2. Update environment variables and contexts to allow collaborators access to necessary secrets.

[rgleason]

🧩 Problem Summary

Collaborator commits trigger CircleCI builds, but Cloudsmith deployment fails. The script ci/cloudsmith-upload.sh runs, but key variables (like the uploader identity) may be unset or misconfigured, especially when collaborators push.
🔍 Key Issues Identified

1. Cloudsmith API Key Scope: Cloudsmith keys are often tied to a specific user. If the key is stored in CircleCI and only valid for your user (rgleason), collaborator-triggered builds may not have access or may fail silently.
2. Environment Variable Access: CircleCI restricts access to secure environment variables (like API keys) on builds from forks or pull requests from external contributors unless explicitly allowed.
3. Script Logic: Your script checks for variables like $CLOUDSMITH_API_KEY, $CIRCLE_USERNAME, and $CIRCLE_PR_USERNAME. If these are unset or empty, the script may skip deployment or fail.

✅ Suggested Fixes and Improvements

1. Use a Machine User for Cloudsmith

• Create a dedicated Cloudsmith account (e.g., shyc-ci-bot) and generate an API key.
• Store this key in CircleCI as CLOUDSMITH_API_KEY.
• This avoids tying deployments to your personal account and ensures collaborators can deploy.

2. Update CircleCI Environment Settings

• Go to your project settings in CircleCI → Environment Variables.
• Ensure CLOUDSMITH_API_KEY is added and marked as accessible to all builds (not just your own).
• If using GitHub SSO or org-level restrictions, confirm collaborators have authorized access2.

3. Improve Script Robustness

Update ci/cloudsmith-upload.sh to include checks and fallbacks:

if [ -z "$CLOUDSMITH_API_KEY" ]; then
  echo "Cloudsmith API key is missing. Skipping upload."
  exit 0
fi

if [ -z "$CIRCLE_USERNAME" ]; then
  echo "CircleCI username not set. Defaulting to 'unknown'."
  CIRCLE_USERNAME="unknown"
fi

echo "Uploading as $CIRCLE_USERNAME..."
# Proceed with upload logic

4. Use CircleCI Contexts for Secure Sharing

• Create a CircleCI Context for shared secrets.
• Assign this context to workflows that need Cloudsmith access.
• This allows collaborators to trigger deployments securely without exposing secrets.

5. Add Logging and Fail-Safes

• Log which user triggered the build.
• Log whether the API key is present.
• Add a dry-run mode for testing collaborator builds without uploading.

🛠️ Optional Enhancements

• Tag-Based Deployment: Only deploy on tagged commits or merges to main to avoid accidental uploads.
• Status Checks: Add GitHub status checks to ensure builds pass before merging.
• Documentation: Add a CONTRIBUTING.md section explaining how collaborator commits trigger builds and deploys.