Initial commit
This commit is contained in:
Zhongwei Li
749
skills/gitlab/references/projects.md
Normal file
749
skills/gitlab/references/projects.md
Normal file
@@ -0,0 +1,749 @@
|
||||
# GitLab Projects Reference
|
||||
|
||||
## Overview
|
||||
|
||||
Projects in GitLab contain your source code, issues, merge requests, and CI/CD pipelines. They are the central hub for all development activity.
|
||||
|
||||
## Project Creation
|
||||
|
||||
### Via UI
|
||||
|
||||
1. Click "+" dropdown > "New project/repository"
|
||||
2. Choose creation method:
|
||||
- Create blank project
|
||||
- Create from template
|
||||
- Import project
|
||||
- Run CI/CD for external repository
|
||||
3. Configure project settings
|
||||
4. Click "Create project"
|
||||
|
||||
### Via API
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
--header "Content-Type: application/json" \
|
||||
--data '{
|
||||
"name": "My Project",
|
||||
"description": "Project description",
|
||||
"visibility": "private",
|
||||
"initialize_with_readme": true,
|
||||
"namespace_id": 123
|
||||
}' \
|
||||
"https://gitlab.com/api/v4/projects"
|
||||
```
|
||||
|
||||
### Via CLI
|
||||
|
||||
```bash
|
||||
# Using glab CLI
|
||||
glab repo create my-project --description "My project" --private
|
||||
```
|
||||
|
||||
## Project Settings
|
||||
|
||||
### General Settings
|
||||
|
||||
**Project Name and Description**:
|
||||
- Name: Display name
|
||||
- Description: Project overview
|
||||
- Project avatar: Custom image
|
||||
- Topics: Searchable tags
|
||||
|
||||
**Visibility**:
|
||||
- Private: Only project members
|
||||
- Internal: Any authenticated user
|
||||
- Public: Everyone (including anonymous)
|
||||
|
||||
**Project URL**:
|
||||
- Namespace: Group or user
|
||||
- Project slug: URL-friendly name
|
||||
|
||||
### Merge Request Settings
|
||||
|
||||
**Merge method**:
|
||||
- Merge commit: Traditional merge
|
||||
- Merge commit with semi-linear history: Rebase then merge
|
||||
- Fast-forward merge: Only if fast-forward possible
|
||||
|
||||
**Merge options**:
|
||||
- Enable "Delete source branch" by default
|
||||
- Enable merge request approvals
|
||||
- Squash commits when merging
|
||||
- Require merge request for push
|
||||
- Enable merge trains
|
||||
|
||||
**Merge checks**:
|
||||
- Pipelines must succeed
|
||||
- All threads must be resolved
|
||||
- Status checks must pass
|
||||
|
||||
### Feature Visibility
|
||||
|
||||
Control feature availability:
|
||||
- Issues
|
||||
- Repository
|
||||
- Merge requests
|
||||
- Forks
|
||||
- CI/CD
|
||||
- Container Registry
|
||||
- Analytics
|
||||
- Requirements
|
||||
- Wiki
|
||||
- Snippets
|
||||
- Pages
|
||||
- Operations
|
||||
|
||||
### Protected Branches
|
||||
|
||||
```bash
|
||||
# Via API
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/protected_branches" \
|
||||
--data "name=main" \
|
||||
--data "push_access_level=40" \
|
||||
--data "merge_access_level=40"
|
||||
```
|
||||
|
||||
**Access levels**:
|
||||
- 0: No access
|
||||
- 30: Developer
|
||||
- 40: Maintainer
|
||||
- 60: Admin
|
||||
|
||||
**Wildcard protection**:
|
||||
```
|
||||
release/*
|
||||
stable-*
|
||||
```
|
||||
|
||||
### Protected Tags
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/protected_tags" \
|
||||
--data "name=v*" \
|
||||
--data "create_access_level=40"
|
||||
```
|
||||
|
||||
## Project Templates
|
||||
|
||||
### Built-in Templates
|
||||
|
||||
GitLab provides templates for:
|
||||
- **Ruby on Rails**
|
||||
- **Spring**
|
||||
- **Express**
|
||||
- **Hugo**
|
||||
- **Jekyll**
|
||||
- **Hexo**
|
||||
- **GitBook**
|
||||
- **Gatsby**
|
||||
- **Nfancy**
|
||||
- **Android**
|
||||
- **iOS (Swift)**
|
||||
- **TYPO3**
|
||||
- **Laravel**
|
||||
- **Salesforce**
|
||||
- And more...
|
||||
|
||||
### Custom Project Templates
|
||||
|
||||
Create custom templates for your organization:
|
||||
|
||||
1. Create a project with desired structure
|
||||
2. Add template files and configuration
|
||||
3. Mark as template (Premium/Ultimate)
|
||||
4. Use in project creation
|
||||
|
||||
### Project Template API
|
||||
|
||||
```bash
|
||||
# List templates
|
||||
curl --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/templates/dockerfiles"
|
||||
|
||||
# Get specific template
|
||||
curl --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/templates/dockerfiles/Ruby"
|
||||
```
|
||||
|
||||
Available template types:
|
||||
- `dockerfiles`
|
||||
- `gitignores`
|
||||
- `gitlab_ci_ymls`
|
||||
- `licenses`
|
||||
|
||||
## Project Import/Export
|
||||
|
||||
### Export Project
|
||||
|
||||
**Via UI**:
|
||||
1. Settings > General > Advanced
|
||||
2. Export project
|
||||
3. Download export file
|
||||
|
||||
**Via API**:
|
||||
```bash
|
||||
# Start export
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/export"
|
||||
|
||||
# Check status
|
||||
curl --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/export"
|
||||
|
||||
# Download
|
||||
curl --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/export/download" \
|
||||
--output project-export.tar.gz
|
||||
```
|
||||
|
||||
### Import Project
|
||||
|
||||
**Via UI**:
|
||||
1. New project > Import project
|
||||
2. Upload export file
|
||||
3. Configure import settings
|
||||
4. Import
|
||||
|
||||
**Via API**:
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
--form "file=@project-export.tar.gz" \
|
||||
--form "path=imported-project" \
|
||||
"https://gitlab.com/api/v4/projects/import"
|
||||
```
|
||||
|
||||
### Import from Other Sources
|
||||
|
||||
**GitHub**:
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
--data "github_personal_access_token=<github_token>" \
|
||||
--data "target_namespace=my-group" \
|
||||
--data "repo_id=123456" \
|
||||
"https://gitlab.com/api/v4/import/github"
|
||||
```
|
||||
|
||||
**Bitbucket**:
|
||||
- Via UI: New project > Import from Bitbucket
|
||||
- Authenticate with Bitbucket
|
||||
- Select repositories
|
||||
|
||||
**GitLab.com to self-hosted**:
|
||||
- Use project export/import
|
||||
- Or remote mirrors
|
||||
|
||||
## Project Members and Permissions
|
||||
|
||||
### Member Roles
|
||||
|
||||
**Guest (10)**:
|
||||
- View issues, merge requests
|
||||
- Leave comments
|
||||
- No repository access
|
||||
|
||||
**Reporter (20)**:
|
||||
- Pull repository
|
||||
- Download artifacts
|
||||
- View CI/CD analytics
|
||||
|
||||
**Developer (30)**:
|
||||
- Push to repository
|
||||
- Create merge requests
|
||||
- Manage issues and MRs
|
||||
- Run CI/CD pipelines
|
||||
|
||||
**Maintainer (40)**:
|
||||
- Manage project settings
|
||||
- Manage team members
|
||||
- Manage protected branches
|
||||
- Deploy to production
|
||||
|
||||
**Owner (50)**:
|
||||
- Delete project
|
||||
- Transfer project
|
||||
- Change project visibility
|
||||
|
||||
### Add Members
|
||||
|
||||
**Via UI**:
|
||||
1. Project > Members
|
||||
2. Invite members
|
||||
3. Select role and expiration
|
||||
4. Send invitation
|
||||
|
||||
**Via API**:
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/members" \
|
||||
--data "user_id=123" \
|
||||
--data "access_level=30"
|
||||
```
|
||||
|
||||
### Share Project with Group
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/share" \
|
||||
--data "group_id=456" \
|
||||
--data "group_access=30" \
|
||||
--data "expires_at=2025-12-31"
|
||||
```
|
||||
|
||||
## Project Badges
|
||||
|
||||
Add badges to display project information:
|
||||
|
||||
```bash
|
||||
# Create badge
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/badges" \
|
||||
--data "link_url=https://example.com" \
|
||||
--data "image_url=https://example.com/badge.svg" \
|
||||
--data "name=Pipeline"
|
||||
```
|
||||
|
||||
**Badge placeholders**:
|
||||
- `%{project_path}`: Project path
|
||||
- `%{project_id}`: Project ID
|
||||
- `%{default_branch}`: Default branch
|
||||
- `%{commit_sha}`: Latest commit SHA
|
||||
|
||||
**Example badges**:
|
||||
```
|
||||
Pipeline: https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
|
||||
Coverage: https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg
|
||||
```
|
||||
|
||||
## Project Milestones
|
||||
|
||||
### Create Milestone
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/milestones" \
|
||||
--data "title=v1.0" \
|
||||
--data "description=First release" \
|
||||
--data "due_date=2025-12-31" \
|
||||
--data "start_date=2025-01-01"
|
||||
```
|
||||
|
||||
### Milestone Burndown Chart
|
||||
|
||||
Track progress with burndown charts (Premium/Ultimate):
|
||||
- Issues opened vs. closed
|
||||
- Weight completion
|
||||
- Time remaining
|
||||
|
||||
## Project Labels
|
||||
|
||||
### Create Labels
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/labels" \
|
||||
--data "name=bug" \
|
||||
--data "color=#FF0000" \
|
||||
--data "description=Bug report" \
|
||||
--data "priority=1"
|
||||
```
|
||||
|
||||
### Scoped Labels
|
||||
|
||||
Create hierarchical labels:
|
||||
- `status::open`
|
||||
- `status::in-progress`
|
||||
- `status::done`
|
||||
- `priority::high`
|
||||
- `priority::low`
|
||||
|
||||
### Label Templates
|
||||
|
||||
Use label templates for consistency:
|
||||
```yaml
|
||||
# .gitlab/labels.yml
|
||||
- name: "bug"
|
||||
color: "#FF0000"
|
||||
description: "Bug report"
|
||||
- name: "feature"
|
||||
color: "#00FF00"
|
||||
description: "Feature request"
|
||||
```
|
||||
|
||||
## Project Webhooks
|
||||
|
||||
Configure webhooks for external integrations:
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/hooks" \
|
||||
--data "url=https://example.com/webhook" \
|
||||
--data "push_events=true" \
|
||||
--data "merge_requests_events=true" \
|
||||
--data "token=secret-token"
|
||||
```
|
||||
|
||||
See `webhooks.md` for detailed webhook documentation.
|
||||
|
||||
## Project Integrations
|
||||
|
||||
### Built-in Integrations
|
||||
|
||||
**Jira**:
|
||||
```bash
|
||||
curl --request PUT --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/services/jira" \
|
||||
--data "url=https://jira.example.com" \
|
||||
--data "username=user" \
|
||||
--data "password=pass" \
|
||||
--data "project_key=PROJECT"
|
||||
```
|
||||
|
||||
**Slack**:
|
||||
```bash
|
||||
curl --request PUT --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/services/slack" \
|
||||
--data "webhook=https://hooks.slack.com/services/..." \
|
||||
--data "username=GitLab" \
|
||||
--data "channel=#general"
|
||||
```
|
||||
|
||||
**Other integrations**:
|
||||
- Asana
|
||||
- Microsoft Teams
|
||||
- Discord
|
||||
- Mattermost
|
||||
- Jenkins
|
||||
- Bamboo
|
||||
- Datadog
|
||||
- Prometheus
|
||||
|
||||
## Project Statistics
|
||||
|
||||
### Get Statistics
|
||||
|
||||
```bash
|
||||
curl --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id?statistics=true"
|
||||
```
|
||||
|
||||
**Available statistics**:
|
||||
- Commit count
|
||||
- Storage size
|
||||
- Repository size
|
||||
- Wiki size
|
||||
- LFS objects size
|
||||
- Job artifacts size
|
||||
- Packages size
|
||||
|
||||
### Contribution Analytics
|
||||
|
||||
View contributor statistics:
|
||||
- Commits per contributor
|
||||
- Additions/deletions
|
||||
- Date range filtering
|
||||
- Export to CSV
|
||||
|
||||
## Project Snippets
|
||||
|
||||
### Create Snippet
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/snippets" \
|
||||
--data "title=Example" \
|
||||
--data "file_name=example.rb" \
|
||||
--data "content=puts 'Hello'" \
|
||||
--data "visibility=private"
|
||||
```
|
||||
|
||||
### Snippet Features
|
||||
|
||||
- Multiple files per snippet
|
||||
- Version history
|
||||
- Comments
|
||||
- Cloning with git
|
||||
- Embedding in web pages
|
||||
|
||||
## Project Wiki
|
||||
|
||||
### Enable Wiki
|
||||
|
||||
```bash
|
||||
curl --request PUT --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id" \
|
||||
--data "wiki_enabled=true"
|
||||
```
|
||||
|
||||
### Create Wiki Page
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/wikis" \
|
||||
--data "title=Home" \
|
||||
--data "content=# Welcome\n\nThis is the home page" \
|
||||
--data "format=markdown"
|
||||
```
|
||||
|
||||
**Supported formats**:
|
||||
- Markdown
|
||||
- RDoc
|
||||
- AsciiDoc
|
||||
- Org
|
||||
|
||||
### Clone Wiki
|
||||
|
||||
```bash
|
||||
git clone https://gitlab.com/group/project.wiki.git
|
||||
```
|
||||
|
||||
## Project Access Tokens
|
||||
|
||||
Create tokens for project automation:
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/access_tokens" \
|
||||
--data "name=Deploy Token" \
|
||||
--data "scopes[]=api" \
|
||||
--data "expires_at=2025-12-31" \
|
||||
--data "access_level=40"
|
||||
```
|
||||
|
||||
## Project Deploy Tokens
|
||||
|
||||
Special tokens for deployment:
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/deploy_tokens" \
|
||||
--data "name=Deploy" \
|
||||
--data "scopes[]=read_repository" \
|
||||
--data "scopes[]=read_registry" \
|
||||
--data "expires_at=2025-12-31"
|
||||
```
|
||||
|
||||
## Project Mirror
|
||||
|
||||
### Push Mirror
|
||||
|
||||
Automatically push changes to remote repository:
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/remote_mirrors" \
|
||||
--data "url=https://github.com/user/repo.git" \
|
||||
--data "enabled=true" \
|
||||
--data "only_protected_branches=false"
|
||||
```
|
||||
|
||||
### Pull Mirror
|
||||
|
||||
Automatically pull changes from remote repository:
|
||||
|
||||
```bash
|
||||
curl --request PUT --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id" \
|
||||
--data "import_url=https://github.com/user/repo.git" \
|
||||
--data "mirror=true" \
|
||||
--data "mirror_trigger_builds=true"
|
||||
```
|
||||
|
||||
## Project Transfer
|
||||
|
||||
### Transfer to Another Namespace
|
||||
|
||||
```bash
|
||||
curl --request PUT --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/transfer" \
|
||||
--data "namespace=new-namespace"
|
||||
```
|
||||
|
||||
**Considerations**:
|
||||
- Updates all URLs
|
||||
- Maintains git remotes
|
||||
- Preserves history
|
||||
- May affect integrations
|
||||
|
||||
## Project Archiving
|
||||
|
||||
### Archive Project
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/archive"
|
||||
```
|
||||
|
||||
**Effects**:
|
||||
- Read-only mode
|
||||
- No new commits/issues/MRs
|
||||
- Maintains visibility
|
||||
- Can be unarchived
|
||||
|
||||
### Unarchive Project
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/unarchive"
|
||||
```
|
||||
|
||||
## Project Deletion
|
||||
|
||||
### Delete Project
|
||||
|
||||
```bash
|
||||
curl --request DELETE --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id"
|
||||
```
|
||||
|
||||
**Delayed deletion** (Premium/Ultimate):
|
||||
- 7-day grace period
|
||||
- Recoverable within period
|
||||
- Permanent after period
|
||||
|
||||
### Restore Deleted Project
|
||||
|
||||
```bash
|
||||
curl --request POST --header "PRIVATE-TOKEN: <token>" \
|
||||
"https://gitlab.com/api/v4/projects/:id/restore"
|
||||
```
|
||||
|
||||
## Project Best Practices
|
||||
|
||||
### 1. Organization
|
||||
|
||||
- Use descriptive names
|
||||
- Add comprehensive README
|
||||
- Document setup process
|
||||
- Maintain CHANGELOG
|
||||
- Include LICENSE file
|
||||
|
||||
### 2. Branch Protection
|
||||
|
||||
- Protect main/master branch
|
||||
- Require merge requests
|
||||
- Enable status checks
|
||||
- Require approvals
|
||||
- Prevent force push
|
||||
|
||||
### 3. Access Control
|
||||
|
||||
- Use least privilege
|
||||
- Regular access reviews
|
||||
- Remove inactive users
|
||||
- Use deploy tokens for CI/CD
|
||||
- Enable 2FA requirement
|
||||
|
||||
### 4. Documentation
|
||||
|
||||
- Keep README updated
|
||||
- Document API endpoints
|
||||
- Include examples
|
||||
- Maintain wiki
|
||||
- Use issue templates
|
||||
|
||||
### 5. Automation
|
||||
|
||||
- Set up CI/CD pipelines
|
||||
- Automate testing
|
||||
- Configure automatic merges
|
||||
- Use scheduled pipelines
|
||||
- Implement code quality checks
|
||||
|
||||
### 6. Security
|
||||
|
||||
- Enable security scanning
|
||||
- Review dependencies
|
||||
- Configure secret detection
|
||||
- Use protected variables
|
||||
- Regular security audits
|
||||
|
||||
### 7. Performance
|
||||
|
||||
- Archive old projects
|
||||
- Clean up old branches
|
||||
- Manage repository size
|
||||
- Optimize CI/CD pipelines
|
||||
- Use caching effectively
|
||||
|
||||
## Project CLI Management
|
||||
|
||||
### Using glab
|
||||
|
||||
```bash
|
||||
# View project
|
||||
glab repo view group/project
|
||||
|
||||
# Clone project
|
||||
glab repo clone group/project
|
||||
|
||||
# Fork project
|
||||
glab repo fork group/project
|
||||
|
||||
# Archive project
|
||||
glab repo archive group/project
|
||||
|
||||
# View project issues
|
||||
glab issue list
|
||||
|
||||
# View merge requests
|
||||
glab mr list
|
||||
```
|
||||
|
||||
## Project API Examples
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import gitlab
|
||||
|
||||
gl = gitlab.Gitlab('https://gitlab.com', private_token='token')
|
||||
|
||||
# Get project
|
||||
project = gl.projects.get('group/project')
|
||||
|
||||
# Update project
|
||||
project.description = 'New description'
|
||||
project.save()
|
||||
|
||||
# Add member
|
||||
project.members.create({
|
||||
'user_id': 123,
|
||||
'access_level': gitlab.const.DEVELOPER_ACCESS
|
||||
})
|
||||
|
||||
# Create label
|
||||
project.labels.create({
|
||||
'name': 'bug',
|
||||
'color': '#FF0000'
|
||||
})
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```javascript
|
||||
const { Gitlab } = require('@gitbeaker/node');
|
||||
|
||||
const api = new Gitlab({
|
||||
token: 'personal-access-token',
|
||||
});
|
||||
|
||||
// Get project
|
||||
const project = await api.Projects.show('group/project');
|
||||
|
||||
// Update project
|
||||
await api.Projects.edit('group/project', {
|
||||
description: 'New description',
|
||||
});
|
||||
|
||||
// Add member
|
||||
await api.ProjectMembers.add('group/project', 123, 30);
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- Project Settings: https://docs.gitlab.com/ee/user/project/settings/
|
||||
- Project Import/Export: https://docs.gitlab.com/ee/user/project/settings/import_export.html
|
||||
- Project Templates: https://docs.gitlab.com/ee/user/project/working_with_projects.html#project-templates
|
||||
- Protected Branches: https://docs.gitlab.com/ee/user/project/protected_branches.html
|
||||
Reference in New Issue
Block a user